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The NetRExx Programming Series 


This book is part of a library, the NetRExx Programming Series, documenting the 
NetRExx programming language and its use and applications. This section lists the 
other publications in this series, and their roles. These books can be ordered in conve- 
nient hardcopy and electronic formats from the Rexx Language Association. 


Quick Start Guide This guide is meant for an audience that has done some pro- 
gramming and wants to start quickly. It starts with a quick 
tour of the language, and a section on installing the NetRExx 
translator and how to run it. It also contains help for trou- 
bleshooting if anything in the installation does not work as 
designed, and states current limits and restrictions of the 
open source reference implementation. 





Programming Guide The Programming Guide is the one manual that at the same 
time teaches programming, shows lots of examples as they 
occur in the real world, and explains about the internals of 
the translator and how to interface with it. 





Language Reference _Referred to as the NRL, this is the formal definition for the 
language, documenting its syntax and semantics, and pre- 
scribing minimal functionality for language implementors. 
It is the definitive answer to any question on the language, 
and as such, is subject to approval of the NetRexx Architec- 
ture Review Board on any release of the language (including 
its NRL). 


Pipelines Reference The Data Flow oriented companion to NetRExx, with its 
CMS Pipes compatible syntax, is documented in this manual. 
It discusses installing and running Pipes for NetRExx, and 
has ample examples of defining your own stages in NetRExx. 
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Typographical conventions 


In general, the following conventions have been observed in the NetRexx publications: 


¢ Body text is in this font 

« Examples of language statements are in a bold type 

¢ Variables or strings as mentioned in source code, or things that appear on the con- 
sole, are in a typewriter type 

¢ Items that are introduced, or emphasized, are in an italic type 

* Included program fragments are listed in this fashion: 


Listing 1: Example Listing 


1 -- Salute the reader 
2 say 'hello reader' 


« Syntax diagrams take the form of so-called Railroad Diagrams to convey structure, 
mandatory and optional items 


Properties 


rae 
visibility modifier deprecated 
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Introduction 


The Programming Guide is the book that has the broadest scope of the publications 
in the NetRExx Programming Series. Where the Language Reference and the Quickstart 
Guide need to be limited to a formal description and definition of the NetRExx language 
for the former, and a Quick Tour and Installation instructions for the latter, this book has 
no such limitations. It teaches programming, discusses computer language history and 
comparative linguistics, and shows many examples on how to make NetRExx work with 
diverse techologies as TCP/IP, Relational Database Management Systems, Messaging 
and Queuing (MQ’) systems, J2EE Containers as JBOSS and IBM WebSphere Appli- 
cation Server , discusses various rich- and thin client Graphical User Interface Options, 
and discusses ways to use NetRExx on various operating platforms. For many people, 
the best way to learn is from examples instead of from specifications. For this reason this 
book is rich in example code, all of which is part of the NetRExx distribution, and tested 
and maintained. 


Terminology 


The NetRexx Language Reference (NRL) is the source of the definitive truth about the 
language. In this Programming Guide, terminology is sometimes used more loosely than 
required for the more formal approach of the NRL. For example, there is a fine line dis- 
tinguishing statement, instruction and clause, where the latter is a more Rexx-like con- 
cept that is not often mentioned in relation to other languages (if they are not COBOL 
or SQL). While we try not to be confusing, clause and statement will be interchangibly 
used, as are instruction and keyword instruction. 
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more than one hundred NetRExx programming examples. The Redbook authors (Peter 
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jnesson, Dave Jones and Salvador Torres) have provided some important documents 
that have shown, in an early stage, how almost everything on the JVM is better and eas- 
ier done in NetRexx. Kermit Kiser also provided examples and did maintenance on the 
translator. Bill Finlason provided the Eclipse instructions. If anyone feels their copyright 
is violated, please do let us know, so we can properly attribute offending passages, or take 
them out2 





2 As the usage of all material in this publication is quoted for educational use, and consists of short fragments, a fair use clause 
will apply in most jurisdictions. 
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Meet the RExx Family 


1.1 Once upon a Virtual Machine 


On the 22nd of March 1979, to be precise, Mike Cowlishaw of IBM had a vision of an 
easier to use command processor for VM, and wrote down a specification over the fol- 
lowing days. VM’ (now called z/VM) is the original Virtual Machine operating system, 
stemming from an era in which time sharing was acknowledged to be the wave of the 
future and when systems as CTSS (on the IBM 704) and TSS (on the IBM 360 Family of 
computers) were early timesharing systems, that offered the user an illusion of having a 
large machine for their exclusive use, but fell short of virtualising the entire hardware. 
The CP/CMS system changed this; CP virtualised the hardware completely and CMS was 
the OS running on CP. CMS knew a succession of command interpreters, called EXEC, 
EXEC2 and Rexx (originally REX - until it was found out, by the IBM legal department, 
that a product of another vendor had a similar name) - the EXEC roots are the explana- 
tion why some people refer to a NetREXx program as an “exec”. As a prime example of a 
backronym, Rexx stands for “Restructured Extended Executor”. It can be defended that 
RExx came to be as a reaction on EXEC2, but it must be noted that both command inter- 
preters shipped around the same time. From 1988 on RExx was available on MVS/TSO 
and other systems, like DOS, Amiga and various Unix systems. RExx was branded the 
official SAA procedures language and was implemented on all IBM’s Operating Systems; 
most people got to know Rexx on OS/2. In the late eighties the Object-Oriented succes- 
sor of Rexx, Object Rexx, was designed by Simon Nash and his colleagues in the IBM 
Winchester laboratory. RExx was thereafter known as Classic Rexx. Several open source 
versions of Classic REXx were made over the years, of which Regina is a good example. 


1.2 Once upon another Virtual Machine 


In 1995 Mike Cowlishaw ported Java’ to OS/2° and soon after started with an experi- 
ment to run RExx on the JVM . With Rexx generally considered the first of the general 
purpose scripting languages, NetRExx is the first alternative language for the JVM. The 
0.50 release, from April 1996, contained the NetRExx runtime classes and a translator 
written in RExx but tokenized and turned into an OS/2 executable. The 1.00 release 
came available in January 1997 and contained a translator bootstrapped to NetRExx. 
The Rexx string type that can also handle unlimited precision numerics is called RExx 
in Java and NetRExx. Where Classic RExx was positioned as a system glue language 
and application macro language, NetRExx is seen as the one language that does it all, 
delivering system level programs or large applications. 
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Release 2.00 became available in August 2000 and was a major upgrade, in which in- 
terpreted execution was added. Until that release, NetRExx only knew ahead of time 
compilation (AOT). 


Mike Cowlishaw took early retirement from IBM in March 2010. IBM announced the 
transfer of NetRExx source code to the RExx Language Association (RexxLA) on June 8, 
2011, 14 years after the v1.0 release, and on the same day, it released the NetRExx source 
code to RexxLA under the ICU open source license. RexxLA shortly after released this 
as NetRExx 3.00 and has followed with updates. 


1.3. Features of NetRExx 


Ease of use The NetRexx language is easy to read and write because many instructions 
are meaningful English words. Unlike some lower level programming languages 
that use abbreviations, NetRExx instructions are common words, such as say, ask, 
if...then...else, do...end, and exit. 

Free format There are few rules about NetRExx format. You need not start an instruc- 
tion in a particular column, you can also skip spaces in a line or skip entire lines, 
you can have an instruction span many lines or have multiple instructions on one 
line, variables do not need to be pre-defined, and you can type instructions in up- 
per, lower, or mixed case. 

Convenient built-in functions NetRExx supplies built-in functions that perform vari- 
ous processing, searching, and comparison operations for both text and numbers. 
Other built-in functions provide formatting capabilities and arithmetic calcula- 
tions. 

Easy to debug When a NetRExx exec contains an error, messages with meaningful ex- 
planations are displayed on the screen. In addition, the trace instruction provides 
a powerful debugging tool. 

Interpreted The NetRexx language is an interpreted language. When a NetRExx exec 
runs, the language processor directly interprets each language statement, or trans- 
lates the program in JVM bytecode. 

Extensive parsing capabilities NetRExx includes extensive parsing capabilities for 
character manipulation. This parsing capability allows you to set up a pattern 
to separate characters, numbers, and mixed input. 

Seamless use of JVM Class Libraries NetRExx can use any class, and class library for 
the JVM (written in Java or other JVM languages) in a seamless manner, that is, 
without the need for extra declarations or definitions in the source code. 
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Learning to program 


2.1 Console Based Programs 


One way that a computer can communicate with a user is to ask questions and then com- 
pute results based on the answers typed in. In other words, the user has a conversation 
with the computer. You can easily write a list of NetRExx instructions that will conduct a 
conversation. We call such a list of instructions a program. The following listing shows a 
sample NetRExx program. The sample program asks the user to give his name, and then 
responds to him by name. For instance, if the user types in the name Joe, the reply Hello 
Joe is displayed. Or else, if the user does not type anything in, the reply Hello stranger is 
displayed. First, we shall discuss how it works; then you can try it out for yourself. 


Listing 2.1: Hello Stranger 


/x% A conversation ,/ 

say "Hello! What's your name?" 
who=ask 

if who = '' then say "Hello stranger" 
else say "Hello" who 


Briefly, the various pieces of the sample program are: 


/* ... */ A comment explaining what the program is about. Where Rexx programs 
on several platforms must start with a comment, this is not a hard requirement for 
NetRexx anymore. Still, it is a good idea to start every program with a comment 
that explains what it does. 


say An instruction to display Hello! What’ s your name? on the screen. 


ask An instruction to read the response entered from the keyboard and put it into the 
computer’s memory. 


who ‘The name given to the place in memory where the user’s response is put. 

if An instruction that asks a question. 

who = ” A test to determine if who is empty. 

then A direction to execute the instruction that follows, if the tested condition is true. 
say An instruction to display Hello stranger on the screen. 


else An alternative direction to execute the instruction that follows, if the tested con- 
dition is not true. Note that in NetRExx, else needs to be on a separate line. 


say An instruction to display Hello, followed by whatever is in who on the screen. 


The text of your program should be stored on a disk that you have access to with the 
help of an editor program. On Windows, notepad or (notepad++), jEdit, X2 or SlickEdit 
are suitable candidates. On Unix based systems, including macOS, vim or emacs are 
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plausible editors. If you are on z/VM or z/OS, XEDIT or ISPF/PDF are a given. More 
about editing NetRExx code in chapter Editor Support, on page D9. 


When the text of the program is stored in a file, let’s say we called it hello.nrx, and you 
installed NetRExx as indicated in the NetRExx QuickStart Guide, we can run it with 


nrc -exec hello 
and this will yield the result: 


NetRexx portable processor, version NetRexx after3.01, build 1-20120406-1326 
Copyright (c) RexxLA, 2011. All rights reserved. 

Parts Copyright (c) IBM Corporation, 1995,2008. 

Program hello.nrx 

===== Exec: hello ===== 

Hello! What’s your name? 


If you do not want to see the version and copyright message every time, which would be 
understandable, then start the program with: 


nrc -exec -nologo hello 
This is what happened when Fred tried it. 


Program hello.nrx 


===== Exec: hello ===== 
Hello! What’s your name? 
Fred 

Hello Fred 


The ask instruction paused, waiting for a reply. Fred typed Fred on the command line 
and, when he pressed the ENTER key, the ask instruction put the word Fred into the 
place in the computer’s memory called “who”. ‘The if instruction asked, is “who” equal 
to nothing: 


who = ’? 
meaning, is the value of “who” (in this case, Fred) equal to nothing: 
"Fred = °? 


This was not true; so, the instruction after then was not executed; but the instruction 
after else, was. 

But when Mike tried it, this happened: 

Program hello.nrx 

===== Exec: hello ===== 

Hello! What’s your name? 


Hello stranger 
Processing of ’hello.nrx’ complete 


Mike did not understand that he had to type in his name. Perhaps the program should 
have made it clearer to him. Anyhow, he just pressed ENTER. The ask instruction put 
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” (nothing) into the place in the computer’s memory called “who”. The if instruction 
asked, is: 


who = ’?’ 


meaning, is the value of “who” equal to nothing: 


In this case, it was true. So, the instruction after then was executed; but the instruction 
after else was not. 


2.2 Comments in programs 


When you write a program, remember that you will almost certainly want to read it 
over later (before improving it, for example). Other readers of your program also need 
to know what the program is for, what kind of input it can handle, what kind of output 
it produces, and so on. You may also want to write remarks about individual instruc- 
tions themselves. All these things, words that are to be read by humans but are not to be 
interpreted, are called comments. To indicate which things are comments, use: 


/x to mark the start of a comment 
x/ to mark the end of a comment. 


The /* causes the translator to stop compiling and interpreting; this starts again only 
after a x/ is found, which may be a few words or several lines later. For example, 


/*x This is a comment. */ 

say text /* This is on the same line as the instruction «/ 
/* Comments may occupy more 

than one line. x/ 


NetREx<x also has line mode comments - those turn a line at a time into a comment. They 
are composed of two dashes (hyphens, in listings sometimes fused to a typographical em 
dash - remember that in reality they are two n dashes. 


-- this is a line comment 


2.3 Strings 


When the translator sees a quote (either ” or’) it stops interpreting or compiling and just 
goes along looking for the matching quote. The string of characters inside the quotes is 
used just as it is. Examples of strings are: 


>Hello’ 
"Final result: ” 


If you want to use a quotation mark within a string you should use quotation marks of 
the other kind to delimit the whole string. 


"Don’t panic” 
*He said, ”Bother”’ 


There is another way. Within a string, a pair of quotes (of the same kind as was used to 
delimit the string) is interpreted as one of that kind. 


’Don’’t panic’ (same as ”Don’t panic” ) 
"He said, ””’Bother””” (same as ’He said, ”Bother”’) 


2.4 Clauses 


Your NetRExx program consists of a number of clauses. A clause can be: 


1. A keyword instruction that tells the interpreter to do something; for example, 
say the word” 
In this case, the interpreter will display the word on the user’s screen. 

2. An assignment; for example, 
Message = ’Take care!’ 

3. A null clause, such as a completely blank line, or 

4. A method call instruction which invokes a method from a class 


>hiawatha’.left(2) 


2.5 When does a Clause End? 


It is sometimes useful to be able to write more than one clause on a line, or to extend a 
clause over many lines. The rules are: 


¢ Usually, each clause occupies one line. 


¢ If you want to put more than one clause on a line you must use a semicolon (;) to 
separate the clauses. 


¢ If you want a clause to span more than one line you must put a dash (hyphen) at 
the end of the line to indicate that the clause continues on the next line. If a line 
does not end in a dash, a semicolon is implied. 


What will you see on the screen when this exec is run? 


Listing 2.2: RAH Exec 


1 /, Example: there are six clauses in this program ,/ say "Everybody cheer!" 
2 say "2"; say "4" 5 say "6" 5; say "8" 5; say "Who do we" - 
3 "appreciate?" 


2.6 Long Lines 


Ever since the days of the punch card images are over, the lines in program sources have 
become longer and longer, and with NetRexx being a free format language, there is no 
real technical reason to limit line length. Still, for readability and for ease access to words 
within a line, it is often indicated to keep lines relatively short and tidy. For this reason, 
the continuation character ’-’ can be used. This also makes it possible to split long literal 
strings over lines. 


Listing 2.3: Long lines 


- 


say 'good' - 
"night! 


nN 


This example will concatenate good’ and ‘night’ with a space inbetween. When you want 
to avoid that, use the ’||’ concatenation operator. 








Listing 2.4: Long lines with string concatenation without space 


say 'good' - 
|| ‘night! 


Noe 


2.7 Loops 


We can go on and write clause after clause in a program source files, but some repetitive 
actions in which only a small change occurs, are better handled by the loop statement. 


Imagine an assignment to neatly print out a table of exchange rates for dollars and euros 
for reference in a shop. We could of course make the following program: 


Listing 2.5: Without a loop 


1 Say 1 'euro equals' 1 y 2.34 'dollars' 
2 say 2 'euro equals! 2 y 2.34 'dollars' 
3 say 3 'euro equals' 3 y 2.34 'dollars' 
4 say 4 'euro equals' 4 y 2.34 'dollars' 
s say 5 'euro equals' 5 y 2.34 'dollars' 
6 say 6 'euro equals' 6 y 2.34 'dollars' 
7 say 7 'euro equals! 7 y 2.34 'dollars' 
8 say 8 'euro equals' 8 y 2.34 'dollars' 
9 say 9 'euro equals! 9 y 2.34 'dollars' 
1 Say 10 'euro equals' 10 y 2.34 'dollars' 


This is valid, but imagine the alarming thought that the list is deemed a success and you 
are tasked with making a new one, but now with values up to 100. That will be a lot of 


typing. 
The way to do this is using the loop4 statement. 


Listing 2.6: With a loop 


1 Loop i=1 to 100 
2 say i 'euro equals! i x 2.34 'dollars' 
3 end 





3Note that Classic Rexx uses do for this purpose. In recent Open Object RExx versions loop can also be used. 
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Now the loop index variable i varies from 1 to 100, and the statements between loop and 
end are repeated, giving the same list, but now from 1 to 100 dollars. 


We can do more with the loop statement, it is extremely flexible. The following diagram 
is a (simplified, because here we left out the catch and finally options) rundown of the 
ways we can loop in a program. 


FIGURE 1: Loop 
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A few examples of what we can do with this: 


























¢ Looping forever - better put, without deciding beforehand how many times 


Listing 2.7: Loop Forever 


1 loop forever 

2 say ‘another bonbon?'! 

3 xX = ask 

4 if x = 'enough already' then leave 

s end 
The leave statement breaks the program out of the loop. This seems futile, but in 
the chapter about I/O we will see how useful this is when reading files, of which we 
generally do not know in advance how many lines we will read in the loop. 


¢ Looping for a fixed number of times without needing a loop index variable 
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Listing 2.8: Loop for a fixed number of times without loop index variable 


1 loop for 10 
2 in.read() /, skip 10 lines from the input file ,/ 
3 end 


« Looping back into the value of the loop index variable 


Listing 2.9: Loop Forever 


1 Loop i = 100 to 90 by -2 
2 say i 
3 end 


This yields the following output: 


90 
Processing of ’test.nrx’ complete 


2.8 Special Variables 


We have seen that a variable is a place where some data, be it character date or numerical 
data, can be held. There are some special variables, as shown in the following program. 


Listing 2.10: NetRExx Special Variables 


1 /y NetRexx ,/ 

2 options replace format comments java symbols binary 
3 

4 class RCSpecialVariables 


5 

6 method RCSpecialVariables() 

7 xX = super.toString 

8 y = this.toString 

9 say '<super>'x'</super>' 

1 say '<this>'y'</this>'! 

nu say '<class>'RCSpecialVariables.class'</class>' 
2 say '<digits>'digits'</digits>' 

3 say '<form>'form'</form>' 

“a say *<[1, 2, 3].length>' 

i say [1, 2, 3].length 

w say '</[1, 2, 3].length>' 

wz say ‘'<null>! 

is «say null 

i say '</null>! 

2 say '<source>'source'</source>' 

2 say '<sourceline>'sourceline'</sourceline>' 
2 say '<trace>'trace'</trace>' 

2 say '<version>'version'</version>' 


2 say ‘Type an answer:' 
2% say '<ask>'ask'</ask>' 


28 return 
30 method main(args = String[]) public static 


32. RCSpecialVariables() 


33 
34 return 


this The special variables this and super refer to the current instance of the class and 
its superclass - what this means will be explained in detail in the chapter Classes 
on page 29, as is the case with the class variable. 

digits The special variable digits shows the current setting for the number of decimal 
digits - the current setting of numeric digits. The related variable form returns the 
current setting of numeric form which is either scientific or engineering. 

null The special variable null denotes the empty reference. It is there when a variable 
has no value. 

source The source and sourceline variables are a good way to show the sourcefile and 
sourceline of a program, for example in an error message. 

trace The trace variable returns the current trace setting, which can be one of the words 
off var methods all results 

version The version variable returns the version of the NetRExx translator that was in 
use at the time the clause we processed; in case of interpreted execution(see chapter 
5] on (19, it returns the level of the current translator in use. 


The result of executing this exec is as follows: 


===== Exec: RCSpecialVariables ===== 
<super>RCSpecialVariablese@4e99353f</super> 
<this>RCSpecialVariables@4e99353f</this> 
<class>class RCSpecialVariables</class> 
<digits>9</digits> 

<form>scientific</form> 

<[1, 2, 3].length> 

3 

</[1, 2, 3].length> 

<null> 


</null> 

<source>Java method RCSpecialVariables.nrx</source> 
<sourceline>21</sourceline> 

<trace>off</trace> 

<version>NetRexx 3.02 27 Oct 2011</version> 

Type an answer: 

hello fifi 

<ask>hello fifi</ask> 


It might be useful to note here that these special variables are not fixed in the sense of 
that they are not Reserved Variables. NetRExx does not have reserved variables and any 
of these special variables can be used as an ordinary variable. However, when it is used 
as an ordinary variable, there is no way to retrieve the special behavior. 





NetRExx Options 


There are a number of options for the translator, some of which can be specified on the 
translator command line, and others also in the program source on the option state- 
ment. In the following table, c stands for commandline only, and b stands for both source 
and commandline. On the commandline, options are prefixed with a dash (“-”), while in 


programsource they are not - there they are preceded by the option statement. 


TABLE 1: Options 































































































Option Meaning Place 
arg words interpret; remaining words are arguments c 
binary classes are binary classes b 
classpath specify a classpath c 
compile compile (default; -nocompile implies -keep) c 
comments copy comments across to generated java b 
compact display error messages in compact form b 
console display messages on console (default) c 
crossref generate cross-reference listing b 
decimal allow implicit decimal arithmetic b 
diag show diagnostic messages b 
ecj prefer the ecj compiler c 
exec interpret with no argument words c 
explicit local variables must be explicitly declared b 
format format output file (pretty-print) b 
java generate Java source code for this program b 
javac prefer the javac compiler c 
keep keep any completed .java file (as xxx.java.keep) c 
keepasjava keep any completed .java file (as xxx.java) c 
logo display logo (banner) after starting b 
prompt prompt for new request after processing c 
savelog save messages in NetRexxC.log c 
replace replace .java file even if it exists b 
sourcedir force output files to source directory b 
strictargs empty argument lists must be specified as () b 
strictassign assignment must be cost-free b 
strictcase names must match in case b 
strictimport | all imports must be explicit b 


Continued on next page 





Table 1 - continued from previous page 
































strictmethods | superclass methods are not compared to local methods for 
best match 

strictprops even local properties must be qualified b 
strictsignal signals list must be explicit b 
symbols include symbols table in generated .class files b 
time display timings c 
trace[n] trace stream [1 or 2], or 0 for NOTRACE b 
utf8 source file is in UTF8 encoding b 
verbose[n]| verbosity of progress reports [0-5] b 
warnexit0 exit with a zero returncode on warnings c 











Options valid for the options statement and on the commandline 


These are the options that can be used on the options statement: 


binary All classes in this program will be binary classes. In binary classes, literals are 





assigned binary (primitive) or native string types, rather than NetRExx types, and 
native binary operations are used to implement operators where appropriate, as 
described in “Binary values and operations”. In classes that are not binary, terms in 
expressions are converted to the NetRExx string type, Rexx, before use by opera- 
tors. 


comments Comments from the NetRExx source program will be passed through to the 


Java output file (which may be saved with a .java.keep or java extension by using 
the -keep and -keepasjava command options, respectively). 


compact Requests that warnings and error messages be displayed in compact form. This 


format is more easily parsed than the default format, and is intended for use by edit- 
ing environments. Each error message is presented as a single line, prefixed with 
the error token identification enclosed in square brackets. The error token iden- 
tification comprises three words, with one blank separating the words. The words 
are: the source file specification, the line number of the error token, the column in 
which it starts, and its length. For example (all on one line): 


[D:\test\test.nrx 3 8 5] Error: The external name 
*>class’ is a Java reserved word, so would not be 
usable from Java programs 


Any blanks in the file specification are replaced by a null (’\0’) character. Additional 
words could be added to the error token identification later. 


crossref Requests that cross-reference listings of variables be prepared, by class. 


decimal Decimal arithmetic may be used in the program. If nodecimal is specified, the 


language processor will report operations that use (or, like normal string com- 
parison, might use) decimal arithmetic as an error. This option is intended for 
performance-critical programs where the overhead of inadvertent use of decimal 
arithmetic is unacceptable. 


diag Requests that diagnostic information (for experimental use only) be displayed. The 


diag option word may also have side-effects. 


12 


explicit Requires that all local variables must be explicitly declared (by assigning them 
a type but no value) before assigning any value to them. This option is intended 
to permit the enforcement of “house styles” (but note that the NetRExx compiler 
always checks for variables which are referenced before their first assignment, and 
warns of variables which are set but not used). 

format Requests that the translator output file (Java source code) be formatted for im- 
proved readability. Note that if this option is in effect, line numbers from the input 
file will not be preserved (so run-time errors and exception trace-backs may show 
incorrect line numbers). 

java Requests that Java source code be produced by the translator. If nojava is specified, 
no Java source code will be produced; this can be used to save a little time when 
checking of a program is required without any compilation or Java code resulting. 


logo Requests that the language processor display an introductory logotype sequence 
(name and version of the compiler or interpreter, etc.). 

sourcedir Requests that all .class files be placed in the same directory as the source file 
from which they are compiled. Other output files are already placed in that di- 
rectory. Note that using this option will prevent the -run command option from 
working unless the source directory is the current directory. 

strictargs Requires that method invocations always specify parentheses, even when 
no arguments are supplied. Also, if strictargs is in effect, method arguments are 
checked for usage - a warning is given if no reference to the argument is made in 
the method. 

strictassign Requires that only exact type matches be allowed in assignments (this is 
stronger than Java requirements). This also applies to the matching of arguments 
in method calls. 

strictcase Requires that local and external name comparisons for variables, properties, 
methods, classes, and special words match in case (that is, names must be identical 
to match). 

strictimport Requires that all imported packages and classes be imported explicitly us- 
ing import instructions. That is, if in effect, there will be no automatic imports, 
except those related to the package instruction. 

strictmethods Superclass methods are not compared to local methods for best match. 

strictprops Requires that all properties, including those local to the current class, be 
qualified in references. ‘That is, if in effect, local properties cannot appear as simple 
names but must be qualified by this. (or equivalent) or the class name (for static 
properties). 

strictsignal Requires that all checked exceptions signalled within a method but not 
caught by a catch clause be listed in the signals phrase of the method instruction. 

symbols Symbol table information (names of local variables, etc.) will be included in 
any generated .class file. This option is provided to aid the production of classes that 
are easy to analyse with tools that can understand the symbol table information. The 
use of this option increases the size of .class files. 

trace, traceX If given as -trace, -tracel1, or -trace2, then trace instructions are accepted. 
The trace output is directed according to the option word: -tracel requests that 
trace output is written to the standard output stream, -trace or -trace2 imply that 
the output should be written to the standard error stream (the default). 
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utf8 If given, clauses following the options instruction are expected to be encoded us- 
ing UTF-8, so all Unicode characters may be used in the source of the program. 
In UTF-8 encoding, Unicode characters less than ’\u0080’ are represented using 
one byte (whose most-significant bit is 0), characters in the range ’\u0080’ through 
’\u07FF’ are encoded as two bytes, in the sequence of bits: 


110xxxxx 10xXxXxXXxXxx 


where the eleven digits shown as x are the least significant eleven bits of the char- 
acter, and characters in the range ’\u0800’ through ’\uFFFF’ are encoded as three 
bytes, in the sequence of bits: 


1110xxxx 10xXxxxxx 1O0xXxxxxx 


where the sixteen digits shown as x are the sixteen bits of the character. If noutf8 
is given, following clauses are assumed to comprise only Unicode characters in the 
range ’\x00’ through ’\xFF; with the more significant byte of the encoding of each 
character being 0. Note: this option only has an effect as a compiler option, and 
applies to all programs being compiled. If present on an options instruction, it is 
checked and must match the compiler option (this allows processing with or with- 
out utf8 to be enforced). 

verbose, verboseX Sets the “noisiness” of the language processor. The digit X may be 
any of the digits 0 through 5; if omitted, a value of 3 is used. The options -noverbose 
and verbose0 both suppress all messages except errors and warnings 


Options valid on the commandline 


The translator also implements some additional option words, which control compila- 
tion features. These cannot be used on the options instruction4, and are: 


arg The -arg words option is used when interpreting programs, it indicates that after the 
-arg statement, commandline arguments for ther interpreted program follow 

classpath The -classpath option allows dynamic specification of the classpath used by 
the NetRexxC compiler without having to depend on the CLASSPATH environ- 
ment variable. (since: NetRExx 3.02) . 

exec The -exec words option is used when interpreting programs. With this option, no 
commandline arguments are possible. 

ecj prefer the ecj compiler when available 

keep keep the intermediate .java file for each program. It is kept in the same directory 
as the NetRExx source file as xxx.java.keep, where xxx is the source file name. The 
file will also be kept automatically if the javac compilation fails for any reason. 

javac prefer the javac compiler when available 

keepasjava keep the intermediate java file for each program. It is kept in the same di- 
rectory as the NetRExx source file as xxx.java, where xxx is the source file name. 
Implies -replace. Note: use this option carefully in mixed-source projects where 
you might have .java source files around. 

nocompile do not compile (just translate). Use this option when you want to use a dif- 
ferent Java compiler. The .java file for each program is kept in the same directory 





4 Although at the moment, there will be no indication of this 
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as the NetRExx source file, as the file xxx.java.keep (where xxx is the source file 
name). 

noconsole do not display compiler messages on the console (command display screen). 
This is usually used with the savelog option. 

savelog write compiler messages to the file NetRExxC.log, in the current directory. This 
is often used with the noconsole option. 

time display translation, javac or ecj compile, and total times (for the sum of all pro- 
grams processed). 

run run the resulting Java class as a stand-alone application, provided that the compi- 
lation had no errors. 

warnexit0 Exit the translator with returncode 0 even if warnings are issued. Useful with 
build tools that would otherwise exit a build. 
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NetRExx as a Scripting Language 


The term scripting is used here in the sense of using the programming language for 
quickly composed programs that interact with some application or environment to per- 
form a number of simple tasks. 


You can use NetRExx as a simple scripting language without having knowledge of, or 
using any of the features that is needed in a Java program that runs on the JVM - like 
defining a class name, and having a main method that is static and expects an array of 
String as its input. 

Scripts can be written very fast. There is no overhead, such as defining a class, construc- 
tors and methods, and the programs contain only the necessary instructions. In this 
sense, a NetRExx script looks like an 00-version of a classic script, as the ceremonial as- 
pects of defining class and method can be skipped. These will be automatically generated 
in the Java language source that is being generated for a script. 


The scripting feature can be used for test purposes. It is an easy and convenient way of 
entering some statements and testing them. ‘The scripting feature can also be used for 
the start sequence of a NetRExx application. 


Scripts can be interpreted or compiled - there is no rule that a script needs to be inter- 
preted. In interpreted mode, the edit-compile-run cycle is shortened, in the sense that 
there is no separate compilation step necessary and incremental editing and testing can 
be done very efficiently. In both cases, interpreted or compiled, the NetRExx translator 
adds the necessary overhead to enable the JVM to execute the resulting program. 


The scripting facility and its automatic generation of a class statement can lead to one 
surprising message when there is an error in the first part of the program: class x already 
implied when the automatically generated class statement (using the program file name) 
somehow clashes with the specified name that contains the error. When not in scripting 
mode, this error message nearly always indicates an error that occurred before the first 
class statement. 
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NetRExx as an Interpreted Language 


In the JVM environment, compilation and interpretation are concepts that are not as 
straightforward as in other environments; JVM code is interpreted on several levels. 
When we are referring to interpreted NetRExx code, we indicate that there is no in- 
termediate Java compilation step involved. A JVM .class file is always interpreted by the 
JVM runtime; the NetRexx translator is able to execute programs without generating 
either .java or .class files. 


This enables a very quick edit-debug-run cycle, especially when combined with the com- 
mand line feature that keeps the translator classes resident (the -prompt option), or one 
of the IDE plugins for NetRExx. 


For NetRexx to deliver this functionality, the translator has been designed to have an 
analogous interpret facility for every code generation part 4 





>This is the right order in which to explain this feature, because historically, the compiler was first (1996) and the interpretation 
facility was added later (in 2000). 
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NetRExx as a Compiled Language 


6.1 Compiling from another program 


The translator may be called from a NetRExx or Java program directly, by invoking the 
main method in the org.netrexx.process.NetRexxC class described as follows: 


Listing 6.1: Invoking NetRexxC.main 


method main(arg=Rexx, log=PrintWriter null) static returns int 


The Rexx string passed to the method can be any combination of program names and 
options (except -run), as described above. Program names may optionally be enclosed 
in double-quote characters (and must be if the name includes any blanks in its specifi- 
cation). 


A sample NetRExx program that invokes the NetRExx compiler to compile a program 
called test is: 


Listing 6.2: Compiletest 


/x compiletest.nrx ,/ 
s='test -keep -verbose4 -utf8' 
say org.netrexx.process.NetRexxC.main(s) 


Alternatively, the compiler may be called using the method: 


Listing 6.3: Calling with Array argument 


method main2(arg=String[], log=PrintWriter null) static returns int 


in which case each element of the arg array must contain either a name or an option 
(except -run, as before). In this case, names must not be enclosed in double-quote char- 
acters, and may contain blanks. 


For both methods, the returned int value will be one of the return values described above, 
and the second argument to the method is an optional PrintWriter stream. If the Print- 
Writer stream is provided, translator messages will be written to that stream (in addition 
to displaying them on the console, unless -noconsole is specified). It is the responsibility 
of the caller to create the stream (autoflush is recommended) and to close it after calling 
the compiler. The -savelog compiler option is ignored if a PrintWriter is provided (the 
-savelog option normally creates a PrintWriter for the file NetRexxC log). 


Note: NetRexxC is thread-safe (the only static properties are constants), but it is not 
known whether javac is thread-safe. Hence the invocation of multiple instances of Net- 
RexxC on different threads should probably specify -nocompile, for safety. 
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6.2 Compiling from memory strings 


Programs may also be compiled from memory strings by passing an array of strings 
containing programs to the translator using these methods: 


Listing 6.4: From Memory 


1 method main(arg=Rexx, programarray=String[], log=PrintWriter null) static returns int 
2 method main2(arg=String[], programarray=String[], log=PrintWriter null) static returns 
int 
Any programs passed as strings must be named in the arg parameter before any pro- 
grams contained in files are named. For convenience when compiling a single program, 
the program can be passed directly to the compiler as a String with this method: 


Listing 6.5: With String argument 


1 method main(arg=Rexx, programstring=String, logfile=PrintWriter null) constant returns 
int 


Here is an example of compiling a NetRExx program from a string in memory: 


Listing 6.6: Example of compiling from String 


1 import org.netrexx.process.NetRexxC 
2 program = "say 'hello there via NetRexxC'" 
3 NetRexxC.main("myprogram", program) 


Programs may also be interpreted directly from memory strings, as shown in on 3-01 


page 87. 
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Calling non-JVM programs 


Although NetREexx currently misses the Address facility that Classic RExx and Object 
Rexx do have, it is easy to call non-JVM programs from a NetRExx program - not as 
easy as calling a JVM class of course, but if the following recipe is observed, it will show 
not to be a major problem. The following example is reusable for many cases. 


Listing 7.1: Calling Non-JVM Programs 


/x script\NonJava.nrx 


This program starts an UNZIP program, redirect its output, 
parses the output and shows the files stored in the zipfile ,/ 


parse arg unzip zipfile . 


-- check the arguments - show usage comments 


if zipfile = '' then do 
say 'Usage: Process unzipcommand zipfile' 
exit 2 
end 
do 
say "Files stored in" zipfile 
say SS" Left (39,3) MSR Left (39,"=") 
child = Runtime.getRuntime().exec(unzip ' -v' zipfile) -- program start 


-- read input from child process 
in = BufferedReader (InputStreamReader (child. getInputStream() )) 
line = in.readline 


start © -- listing of files are not available yet 
count 0 
loop while line \= null 
parse line sep program 
if sep = Sss=ess ' then start = \start 
else 
if start then do 
count = count + 1 
if count // 2 > © then say program.word(program.words).left(39) '\-' 
else say program.word(program.words) 


end 
line = in.readline() 
end 


-- wait for exit of child process and check return code 
child.waitFor() 
if child.exitValue() \= 0 then 

say 'UNZIP return code' child.exitValue() 


catch IOException 
say 'Sorry cannot find' unzip 
catch e2=InterruptedException 
e2.printStackTrace() 
end 


Just firing off a program is no big deal, but this example (in script style) shows how 
easy it is to access the in- and output handles for the environment that executes the 


23 


a4 
2 
3 
4 
5 
6 
a 
8 
9 


program, which enables you to capture the output the non-jvm program produces and 
do useful things with it Line 17 starts the external command using the JVM Runtime 
class in a process called child. In line 20 we create a BufferedReader from the child 
processes’ output. This is called an InputStream but it might as well have been called an 
OutputStream- everything regarding I/O is relative - but fortunately the designers of the 
JVM took care of deciding this for you. In lines 25-35 we loop through the results and 
show the files stored in the zipfile. Note that we do (line 14) have to catch (line 42) the 
IOException that ensues if the runtime cannot find the unzip program, maybe because 
it is not on the path or was not delivered with your operating system. 


Starting from JVM 1.5 releases, there is a new way to accomplish the same goal, in a 
cleaner manner and with the added bonus of being able to redirect streams, and use 
environment variables. In this regard, the environment variable has made an important 
comeback from having its calls deprecated, to easy to use support in the ProcessBuilder 
class. 


Listing 7.2: Use of ProcessBuilder 


lx 
x Class OSProcess implements ways to execute and get output from an OS Process 


x/ 


class OSProcess 


properties indirect 

pid = Process 

returncode 

commandList = ArrayList() 
outList = ArrayList() 


properties private 
listeners = HashSet() 
lex 

x Default constructor 


ry) 
method OSProcess() 
return 


lx 
x helper method that makes an ArrayList of out a Rexx string for use 
* in the similarly named method that has an ArrayList as input 


x/ 
method outtrap(command_=Rexx) returns ArrayList 
if command_ = '', command_ = null then return null 


a = ArrayList() 

loop until command_ = '' 
parse command_ first command_ 
a.add(first.toString() ) 

end 

return this.outtrap(a) 


Ix 


y helper method that makes an ArrayList of out a Rexx string for use 
% in the similarly named method that has an ArrayList as input 


x/ 
method exec(command_=Rexx, wait=1) 
if command_ = '', command_ = null then return 


a = ArrayList() 

loop until command_ = '' 
parse command_ first command_ 
a.add(first.toString() ) 

end 

this.exec(a,wait) 


lex 





®This is akin to what one would do with queue on z/VM CMS and outtrap on z/OS TSO in Classic Rexx. 
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47 x Method outtrap starts an OS process from a command line in an ArrayList 
48 x @param command is a List that has the command to be executed as elements 
49 x @return List containing the output of the command 


5k / 

s1 method outtrap(command_=ArrayList) returns ArrayList 
52 this.commandList = command_ 

53 do 

54 pb = ProcessBuilder (command_) 
55 pb. redirectErrorStream(1) 

56 this.pid = pb.start() 

57 in = BufferedReader (InputStreamReader (this.pid.getInputStream() ) ) 
58 line = Rexx in.readLine() 

59 loop while line <> null 

60 this.outList.add(line) 

61 line = Rexx in.readLine() 

62 end 

63 pid.waitFor() 

64 returncode = pid.exitValue() 
65 return this.outList 

66 catch iox=IOException 

67 say iox.getMessage() 

68 return ArrayList() 

69 catch InterruptedException 

70 say "interrupted" 

7 return ArrayList() 

72 end -- do 

73 

ma kx 


75 x Method exec starts an OS process from a command line in an ArrayList 
76 x @param then fires off outputEvent events to every registered listener 
7 x @return void 


78 zy 

7 method exec(command_=ArrayList,wait=1) 
80 this.commandList = command_ 

81 do 

82 pb = ProcessBu7ilder (command_) 

83 pb. redirectErrorStream(1) 

84 this.pid = pb.start() 

85 if wait then do 


86 in = BufferedReader (InputStreamReader (this.pid.getInputStream() ) ) 
87 line = in.readLine() 
88 loop while line <> null 


89 line = in.readLine() 

90 i = this.listeners.iterator() 

91 loop while i.hasNext() 

92 op = OutputEventListener i.next() 

93 op.outputReceived(OutputLineEvent (this, Line, this.pid)) 
94 end 

95 end 


96 pid.waitFor() 
97 returncode = pid.exitValue() 


98 end 

99 catch iox=IOException 

100 say iox.getMessage() 

101 catch InterruptedException 
102 say "interrupted" 

103 end -- do 

104 

105 

ws / Kx 


107 x Method addOutputEventListener supports registering an event Listener 
108 x @param Listener_ is a OutputEventListener 


x 
uo method addOutputEventListener (listener_=OutputEventListener) 
ul this. listeners.add(listener_) 


113 fx 
14 x Method removeOutputEventListener supports de-registering an event listener 


us x @param Listener_ is a OutputEventListener 


116 gf 
uz method removeOutputEventListener (Listener_=OutputEventListener) 
1s this. listeners. remove(listener_) 
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In the above sample, we are using two different ways to obtain the output from a process 
started by the JVM from our own program. The method outtrap waits until the invoked 
process is finished and returns all output lines in an ArrayList. Its name is not entirely 
coincidental with the similar TSO outtrap function. 


Sometimes we cannot wait until the child process is finished, for example when it is a 
long running process and we need to capture the output on a line-by-line basis to see 
what is happening - in case of the example, this was done to capture the output as part 
of a testsuite for a multithreaded file transfer application, which has a server resident 
process that is not supposed to end, because one of its tasks is to poll a directory for 
incoming files with a specific pattern in the file names. This is implemented using an 
Event based pattern (as explained in on page B4 


Listing 7.3: Output Line Event 


1 import java.util.EventObject 
2 kx 
3 x Class OutputLineEvent embodies the OutputLineEvent 


«/ 


class OutputLineEvent extends EventObject 


properties indirect 


4 
§ 
6 
7 
s pid = Process 
9 


line 
w |x 
u x Default constructor 
na x/ 
13 =©method OutputLineEvent (ob=Object,line_, pid_=Process) 
4 super (ob) 
15 this.line = line_ 
16 this.pid = pid_ 
17 return 


Listing 7.4: Output Event Listener 


1 import java.util.EventListener 
2 /kx 
3 y Interface OutputEventListener specifies the one mandatory method for this interface 


4 x/ 

s class OutputEventListener interface implements EventListener 
6 

7 method outputReceived(ob=OutputLineEvent) 


The call would look something like this: 


Listing 7.5: Example of calling the OSProcess class - registering an eventhandler 





1 os = OSProcess() 
2 os.addOutputEventListener (this) 
3 os.exec (command) 


The class must extend OutputEvenListener, and implement this method: 


Listing 7.6: Example of implementing the listener method 


1 method outputReceived(ob=OutputLineEvent) 
2 this.counter = this.counter+1 
3 say this.counter ob.getPid() ob.getLine() 
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Using NetRExx classes from Java 


If you are a Java programmer, using a NetRExx class from Java is just as easy as using 
a Java class from NetRExx. NetRExx compiles to Java classes that can be used by Java 
programs. You should import the netrexx.lang package to be able to use the short class 
name for the Rexx (NetRExx string and numerics) class. 


A NetRexx method without a returns keyword can return nothing, which is the void 
type in Java, or a Rexx string. NetRExx is case independent®; Java is case dependent. 
NetRExx generates the Java code with the case used in the class and method instruc- 
tions. For example, if you named your class Spider in the NetRexx source file, the re- 
sulting Java class file is Spider.class. The public class name in your source program must 
match the NetRExx source file name. For example, if your source file is SPIDER.NRX, 
and your class is Spider, NetRExx generates a warning and changes the class name to 
SPIDER to match the file name. A Java program using the class name Spider would not 
find the generated class, because its name is SPIDER. class - if the compile succeeded, 
which is not guaranteed in case of casing mismatches. If you have problems, compile 
your NetRExx program with the options -keepasjava -format. You then can look at the 
generated java file for the correct spelling style and method parameters. 





7 With the default of options nostrictcase in effect. 
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Classes 


Somewhere in the nineties Object Orientation became one of the mainstream ways 
to organize computer programs, and support for this was added to programming lan- 
guages. C became C++ with a preprocessor that generates C4 that is not entirely unlike 
the NetRexx translator produces Java. Java in itself is syntax-wise a cleaned up version 
of C++, but in essence an entirely different language. Its inventor and architect, James 
Gosling, has stated on various occasions that he was planning a fully different syntax for 
what finally became Java - but that Sun management more or less forced him to use a 
C++ derived syntax, because C++ compilers was what SUN did well at the time. With 
Brendan Eich having to base JavaScript qua naming and syntax on Java, the circle that 
brought the world terse, curly braces based notations, is complete. 


For an audience of RExx programmers, the usual OO presentation goes into the advan- 
tages of the paradigm. Today, that is not really necessary, and OO is a given; it slightly 
deviates from earlier notation as result of trying to put data and procedure into Objects, 
but it is no great deal, and this NetRExx Programmer's Guide does not need a special 
section on the benefits of the OO paradigm. It is assumed that with a few examples ev- 
eryone should be able to get it; some old programmers might resist but there is really no 
use in fighting the mainstream. Consequently, this section discusses the way to do this 
in NetRExx; the way NetREexx does it is for a very large part formed by the way the JVM 
dictates it, adapted to Rexx notational style and conventions. 


Where traditional RExx would say: 
l=left(ourstring,1) 

the OO-versions of RExx would say: 
l=ourstring. lLeft(1) 


As often the case, the hard part is in the notational ommission that OO has as its char- 
acteristic: the instance pointer is no part of the function call and has moved to the left 
(in what now is called a method. The weight has shifted from the operation to the object 
it is called on. 


9.1 Classes 


Classes represent a blueprint, ‘cookie cutter’ approach in creating objects that do useful 
things. A class is defined in a file by the same name (exceptions here for dependent 
classes). So a class called Cookie is defined in a file called Cookie.nrx. Its real, which 





8 Cfront 
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means its most specific name, including its package specification, is not given by the 
file name but by the combination of the class=file + the name given on the package 
statement. This enables one to put classes in different packages without having to change 
the file names. 


9.2 Dependent Classes 


Dependent Classes are the NetRExx way to implement Java minor classes. There is no in- 
line definition possible, and dependent classes need their own class definition, but can be 
defined in the same source file as the classes they depend on. The notational advantage of 
nested’ class definition, like customary in (for example) Java Swing programs is absent. 
What is present, is the way dependent classes can seamlessly access properties of their 
parent classes. 


9.3. Properties 


The properties statement enables us to define variables that are global to the class defi- 
nition, and as such can be used by all methods of the class. 


A properties statement needs at least one visibility or modifier keyword. When this is 
left out, a variable called “properties” is defined, which is not an error, but (most of the 
times) not what was intended. 


Because the properties of a class can be externally visible (depending on visibility they 
need to have a type. When the type is omitted in the definition, they are of type Rexx. 
So-called indirect properties, defined with the properties indirect modifier, give rise 
to automated generation of getter and setter methods for use in Java Beans. 
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Using Packages 


Any non-toy, non-trivial program needs to be in a package. Only examples in program- 
ming books (present company included) have programs without package statements. 
The reason for this is that there is a fairly large chance that you will give something a name 
that is already used by someone else for something else. Things are not their names, and 
the same names are given to wildly dissimilar things. The package construct is the ]VM’s 
approach to introducing namespaces into the total set of programs that programmers 
make. Different people will probable write some method that is called ListDif ferences 
sometime. With all my software in a package called com. frob.nitz and yours in a pack- 
age called com. frob.otzim, there is no danger of our programs calling the wrong class 
and listing the wrong differences. 


It is imperative to understand this chapter before continuing - it is a mechanical nuts- 
and-bolts issue but an essential one at that. 


10.1 The package statement 


The final words about the NetRExx package statement is in the NetRExx Language Ref- 
erence, but the final statement about the package mechanism is in the JVM documenta- 
tion. 


10.2 Translator performance consequences 


Because the NetRexx translator has to scan all packages that it can see (meaning a recur- 
sive scan of the directories below its own level in the directory tree, and on its classpath, 
it is often advisable (and certainly if . (a dot, representing the current directory) is part of 
the classpath) to do development in a subdirectory, instead of, for example, the top level 
home directory. If a large number of packages and classes are visible to the translator, 
compile times will be negatively impacted. 


10.3 Some NetRExx package history 


All IBM versions of NetRExx had the translator in a package called 


COM.ibm.netrexx.process 





9 Willard Van Orman Quine, Word and Object, MIT Press, 1960, ISBN 0-262-67001-1 
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The official, SUN ordained convention for package names was, to prepend the reversed 
domain name of the vendor to the package name, while uppercasing the top level do- 
main. NetRExx, being one of the first programs to make use of packages, followed this 
convention, that was quickly dropped by SUN afterwards, probably because someone ex- 
perienced what trouble it could cause with version management software that adapted 
to case-sensitive and case-insensitive file systems. For NetRExx, which had started out 
keenly observing the rules, this insight came late, and it is a sober fact that as a result 
some needlessly profane language was uttered on occasion by some in some projects that 
suffered the consequences of this. With the first RexxLA release of NetRExx in 2011, the 
package name was changed to org.netrexx, while the runtime package name was kept 
as netrexx. Lang, also because some major other languages follow this convention. 


10.4 CLASSPATH 


Most implementations of Java use an environment variable called CLASSPATH to indi- 
cate a search path for Java classes. The Java Virtual Machine and the NetRExx transla- 
tor rely on the CLASSPATH value to find directories, zip files, and jar files which may 
contain Java classes. The procedure for setting the CLASSPATH environment variable 
depends on your operating system (and there may be more than one way). 


¢ For Linux and Unix (BASH, Korn, or Bourne shell), use: 


CLASSPATH=<newdir>:\SCLASSPATH 
export CLASSPATH 


¢ Changes for re-boot or opening of a new window should be placed in your /etc/pro- 
file, login, or .profile file, as appropriate. 
¢ For Linux and Unix (C shell), use: 


setenv CLASSPATH <newdir>:\SCLASSPATH 


Changes for re-boot or opening of a new window should be placed in your .cshrc 
file. If you are unsure of how to do this, check the documentation you have for 
installing the Java toolkit. 

¢ For Windows operating systems, it is best to set the system wide environment, 
which is accessible using the Control Panel (a search for “environment” offsets the 
many attempts to relocate the exact dialog in successive Windows Control Panel 
versions somewhat). 
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Programming Patterns 


Much has been made of patterns as aggregations of higher level embodiments of pro- 
gramming solutions. It has been observed that of a number of the C++ oriented pat- 
terns in Design Patterns", some owe their existence to complications in the C++ lan- 
guage and are not readily reproducible in a Java Patterns or Ruby Patterns book. The 
same goes for NetRexx- in this chapter we would like to present a number of Java pat- 
terns usable in NetRexx, and a number of patterns that are unique to NetRexx. 


11.1 Singleton 


Sometimes we only want one instance of a class, and we want every user of the class to 
refer to that same instance. In this case, we need to adapt the class construction mecha- 
nism to make sure this happens. There are different ways to implement this, one way is 
shown below. 


Listing 11.1: Singleton 


class TheGatherer 


properties static 
instance = TheGatherer 


method getInstance() returns TheGatherer static protect 
if TheGatherer.instance <> null then 
do 
return TheGatherer.instance 
end 
else 
do 
TheGatherer.instance = TheGatherer () 
return TheGatherer.instance 
end 


lke 
* private constructor enforces singleton 


* 
method TheGatherer() private signals ClassNotFoundException 


The way that has been chosen here is to make the constructor private, so no other class 
can use it. We need an alternative method to make the first and only instance of this 
class, and this is the getInstance() method. This checks if a static property instance 
is null, in which case the private constructor is run and its return value put in instance. 
Every subsequent call to getInstance() sees the value of the static variable instance 
being not null, and returns that value, which now refers to the single instance. There are 





10This observation from a Java patterns book. 
11Gamma, Helm, Johnson, Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley Profes- 
sional; 1994 
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several ways to enhance this method, but this is a simple way and it fits the bill. For added 
security, override the methods for class serialization. 


There is a common naming pattern for Singletons, which is the prepend the name of the 
class with The, as in the above example. 


11.2 Observable and Events 


The observer pattern can also be referred to as Callback, and the Java Event class delivers 
support for it. It is very usable if some result needs to be available for a set of callers, where 
the set is 0 to many. It works as follows: (see a simple implementation in section [7.4] on 
page 26) An object, maintains a list of its dependents, called observers, and notifies them 
automatically of any state changes, usually by calling one of their methods. It is mainly 
used to implement distributed event handling systems. The Observer pattern is also a key 
part in the familiar Model View Controller (MVC) architectural pattern. In the JVM, this 
object needs to implement the methods of the Listener interface; this interface specifies 
the addListener and RemoveListener methods; it keeps a collection in which references 
to the added listener objects are maintained. The listening is done to subclassed Java 
Event classes. The event specifies the method to be called when ’firing off’ and event. 
This means that this method is called on every listener. 


One of the larger benefits: it decouples the observer from the subject. The subject doesn't 
need to know anything special about its observers. Instead, the subject simply allows 
observers to subscribe. When the subject generates an event, it simply passes it to each 
of its observers. Another benefit is that event consuming classes don't have to wait until 
a process is finished, and can consume events as they come in. The OSProcess class on 
page 24) uses an event approach to consume output lines from a subprocess - in the 
version that puts the output in an ArrayList needs to wait for the subprocess to end, but 
the event driven version can monitor a long running process and analyze output lines 
whenever they are received. 


11.3. Recursive Parse 


This is a pattern unique to Rexx, by virtue of Rexx having the Parse statement. It also 
works in NetRexx. 


11.4 More Observer/Observable 


Java has special support for the Observer/Observable pattern in the form of the Observer 
class and the Observable interface. In the following snippet one can see the Observer class 
in working. 

The class is the same singleton as shown above, and starts several threads which need to 
be observed. 


Listing 11.2: Observer 


1 Class TheGatherer implements Observer 
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The Observable threads need to implement the Observable interface, and to be able to 
be started as a thread, Runnable. This is how we start it; its definition follows. 


Listing 11.3: Observable: starting Observable Threads 


1 method TheGatherer() private signals ClassNotFoundException 
2 logger_.info( "TheGatherer: start") 

3 tl = TransactionStatusMonitor (Rexx 10000) 

4 t1l.addObserver (this) 

5 Thread(t1).start() 

6 logger_.info( "TheGatherer: started thread TransactionStatusMonitor") 


We instantiate the Observable class as t1, and add the instance of our Observer class, 
TheGatherer, to it as Observer. After we have done this, we start it by instantiating a 
Thread object with it and calling the start method, which, by virtue of it implementing 
the Runnable interface, starts its run method. 


Note that the TransactionStatusMonitor extends a class called Monitor, which in turn, 
implements the Observable interface. The reason for this is, we run several monitoring 
threads, and they all behave in the same way. 


Listing 11.4: The Monitor Superclass 


1 import java.util.Observable 
2 class Monitor extends Observable 


properties public 
logger_ = Logger.getLogger (Monitor.class.getName() ) 
sleeptime 


properties static 
da = TheDataAccess null 


u method Monitor () 
2 this.da = TheDataAccess.getInstance() 


Listing 11.5: an Observable Thread 


class TransactionStatusMonitor implements Runnable extends Monitor 


method TransactionStatusMonitor(s) signals ClassNotFoundException 
this.sleeptime = s 


method run() 


1 
2 
3 
4 
5 
6 
7 
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do 
loop forever 

pi = this.da.idealql1() 
10 if pi.getID().length() < 5 then 
ll do 
12 nop 
B end 
4 else do 
15 pi.setIdType('ideal') 
16 ibidp = this.da.getIBPostIDStatuses (pi) 
7 setChanged() 
18 notifyObservers(ibidp. getStatusDelta() ) 
19 end 
20 
21 Thread.currentThread().sleep(this.sleeptime) -- sleep for sleeptime seconds 
2 end 
23 catch InterruptedException 
24 parse source s 
25 say "thread interrupted:" s 
26 end 


In lines 17 an 18 the magic happens: the setChanged() method sets the status of this 
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instance as updated, and the notifyObservers() method calls for all the registered Ob- 
servers their update() methods; this has the following signature: 


Listing 11.6: the update() method 


1 method update(o=Observable,obj=Object) protect 
2 cl = o.getClass().getName() 


The update() method receives an Object. The . getClass. getName call is for illustrative 
purposes and can be used to decide how to treat the received update object. 
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Incorporating Class Libraries 


12.1 A Word About Java Generics 


Many classes in Java are expressed as generics. It is important to note that the generic 
is a compile time only java type enforcement mechanism, and therefore does not affect 
NetRExx. 


A generic class has, underlying it, a class that accepts one or more objects as parameters 
- taking as an example the ArrayList class, the Java documentation shows that this has 
a class signature of public class ArrayList<E> with one of the constructors being 
ArrayList() and, for example, a method add(E e). If the Arraylist is instantiated in 
Java as follows:- 


ArrayList<String> stringList = new ArrayList<String>(); 


then the Java compiler will note that the ArrayList is instantiated with a <String> object 
- and will enforce String usage everywhere else that the <E> is used in the class documen- 
tation - in this case the type add(E e). 


Thus 

stringList.add(”Item”) ; 

will be permitted by the compiler, since a string is being added. In contrast, 
stringList.add(new Integer(7)); 


will fail since a string is not being added. 


Remembering that the ArrayList deals directly with objects the following short NetRExx 
program will correctly use ArrayList without worrying about the “complication” of 
generics. 


Listing 12.1: ArrayList Example 


al = ArrayList() -- An ArrayList just deals with Objects 
al.add("Eric") -- so we give it some Rexx objects 
al.add("Erica") 

num = 0 


al.add (num) 

say "There are" al.size "elements in the list" -- and show they are present 
/% Now, to retrieve them ,/ 

loop item over al 


say item 
end 
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If one does not need generics, then it could be asked why they have been implemented at 
all - the answer is that they prevent many Java run-time errors resulting from a failure to 
cast the object used to the correct type. When programming in NetReExx the use of the 
“universal” Rexx class means that this is rarely an issue. When retrieving objects from a 
generic class used from within Java one must remember to use the correct type, cast or 
the binary option just as would be expected when using a Java object in any other way. 


12.2 The Collection Classes 


The Java collections framework (JCF) is a set of classes and interfaces that implement 
commonly reusable collection data structures. The JCF provides both interfaces that de- 
fine various collections and classes that implement them. Collection implementations 
in pre-JDK 1.2 versions of the Java platform included few data structure classes, but did 
not contain a collections framework. The standard methods for grouping Java objects 
were Via the array, the Vector, and the Hashtable classes, which were not easy to extend, 
and did not implement a standard member interface. The collections framework was 
designed and developed primarily by Joshua Bloch, and was introduced in JDK 1.2. 


Almost all collections in Java are derived from the java.util.Collection interface. 
Collection defines the basic parts of all collections. The interface states the add() and 
remove() methods for adding to and removing from a collection respectively. Also 
required is the toArray() method, which converts the collection into a simple ar- 
ray of all the elements in the collection. Finally, the contains() method checks if 
a specified element is in the collection. The Collection interface is a subinterface of 
java.util.Iterable, so any Collection is iterable (using an iterator for a loop over the 
contents). All collections have an iterator that goes through all of the elements in the 
collection. 


The Collection framework is one of the aspects of where NetRExx relegates to Java for 
its implementation. Where ooRExx has had its collection classes in the language def- 
inition from day one, in NetREexx they are not part of the language; most of the data 
related support is in the indexed strings feature. This, in turn, makes use of the Dictio- 
nary mechanism already implemented in the earliest versions of Java; NetRExx language 
design was long complete when JDK 1.2 came out. 


The Pre-Java Generic classes JFC had, in order to be generic, an interface in which objects 
could be added in as a java.lang.Object, but on return, that object needed to be typecast 
to the right type. Using collection classes did entail a good deal of casting return values, as 
type RExx was not part of the set of types that collections had native support for. Modern 
NetRexx versions have builtin support for using type Rexx in collection classe4, so 
these can be added to and retrieved from collection classes without further ado. 


The NetRexx native Rexx datatype contains a Java Hashtable which is part of the Collec- 
tions Framework. New classes, constructors and methods have been added to implement 
the Java Map interface and allow better interoperation with Java. Some of the new collec- 
tions support methods include isindexed() to checkifa Map currently exists, size() to 
determine the count of map entries and buildmap (sequencel, sequence2) to construct 
Rexx maps from arrays or Java Lists. Other classes and methods are documented in the 





12Tn actuality, the needed interfaces, like Comparable and Comparator are now provided in the RExx type 
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Java Collections Map interface Javadocs. ”isindexed()” returns 0 if no indexed values ex- 
ist and 1 if there is at least one indexed value in a Rexx object. To build a new indexed 
Rexx map with the buildmap method you can do this: Rexx (default) .buildMap (keys, 
values) where keys and values are any arrays or Java collections framework Lists and 
default is the default value for the Rexx variable (using the standard Rexx constructors). 


All elements are converted to strings before being added to the indexed Rexx variable 
which is returned. Null can be passed for one of the keys or values parameters to default 
to a 1-n integer sequence matching the other parameter but if both parameters are pro- 
vided they must have the same length. Note that arrays do not need to be string arrays 
and that primitive arrays such as int[] are also accepted. 


Collection is a Java generic. Any collection can be written to store any class. For ex- 
ample, Collection<String> can hold strings, and the elements from the collection can 
be used as strings without any casting required. NetRExx 3.02 added loop over sup- 
port in NetRExx programs for collection classes; this has been implemented without 
the need for Java generics. This makes it impossible to use the generics mechanism to 
constrain collection class membership to a specified type. This, however, can be easier 
accomplished by subclassing the collection class and overriding its constructors. 
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Input and Output 


A conscious design decision was to leave I/O operations out of the language, and to 
wholly depend on the JVM functionality for this. This turned out to be a good decision, 
as JVM I/O has been enhanced and changed over the years; also, the various environ- 
ments in which NetRExx can be used as a programming language, are not limited to file 
I/O, but have various implementations to interact with the outside world. A NetRExx 
program that employs Flash technology has different method calls to make than a pro- 
gram that uses ISPF for user interaction. 


This does not preclude us to implement file I/O in a way that is reminiscent of Classic 
Rexx, and in fact this has been done, and the future might see some standarization in this 
respect. The contrib part of the NetRExx source code repository has various examples of 
how this is done. In the remaining part, however, we are discussing how to use standard 
JVM libraries to accomplish I/O. 


13.1 Improvements in 3.07 to Say and File reading 


Starting with version 3.07 it became a bit easier, c.q. less verbose, to print directy to a 
a file using the Say statement, or, for example, to a file and to Stderr. Also, a pattern in 
which there is an action for every line in a file, is now supported with the oneliner file 
handler, RexxlO.forEachLine. 


This is shown in the figures 2, B| and 4 


13.2 The File Class 


13.2.1 Line mode I/O using BufferedReader and FileOutputStream 


Listing 13.1: Buffered I?0 


/x linecomment.nrx -- convert appropriate block comments to line comments ,/ 


/x This is a sample file input and output program, showing how to open, 
check, and process text files, and handle exceptions. 
Note the use of the Reader and Writer classes, which convert your 
local computer's 'code page' (character encoding) to Unicode during 
reading and back again during writing. ,/ 


parse arg fin fout . -- get the arguments: input and output files 
if fout='' then do 

say '# Please specify both input and output files' 

exit 1 
end 
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lass ZzFacilityReport 


properties inheritable : 
bpSet = TreeSet() 
yee 
* Default constructor 
“7 
method ZzFacilityReport() 
return 
method mainCargs=String[]) static 
z = ZzFacilityReport() 
RexxI0. setOutputStream(FileOutputStream(' fiscfac.csv')) 
RexxI0().File('data/erp_wb_dpsob_bp_acc.txt').forEachline(z.file1()) 
RexxI0().File('data/pri_zzfacility.txt').forEachline(z.file2Q) 
class ZzFacilityReport.filel dependent implements LineHandler 
method handleCin) an er 
parse in '|'."I'bp'l' . 
Parent. bpSet.addbp. strip) minor class and inheritable 
class ZzFacilityReport.file2 dependent implements LineHandler 
method handleCin) 
z = ZzFacilityO 
z.parseCin) = 
if z.getPARTNER = '' then return = 
if parent.bpSet.contains(z.getPARTNER.strip) then return = 
if z.getPARTNER = 'PARTNER' then return a 
if z.getZZACTVTSTART = '' then z.setZZACTVTSTARTC'@1.01.1900') : 





FIGURE 2: Oneliner file handler 


/x Open and check the files ,/ 
do 
infile=File(fin) 
instream=Fi LeInputStream(infile) 
inhandle=BufferedReader (InputStreamReader (instream) ) 
outfile=File(fout) 
if outfile.getAbsolutePath=infile.getAbsolutePath then do 
say '# Input file cannot be used as the output file' 
exit 1 
end 
outstream=FileOutputStream(outfi le) 
outhandle=OutputStreamWriter (outstream) 
say 'Processing' infile'...' 
catch e=IOException 
say '# error opening file' e.getMessage 
end 


lLinesep=System. getProperty('line.separator') -- be platform-neutral 


/x The main processing loop ,/ 
loop linenum=1 by 1 


line=Rexx inhandle.readLine -- get next line [as Rexx string] 
if Line=null then leave Linenum -- normal end of file 
parse line pre '/,' mid ',/' post -- process the line 


if pre\='' then 
if mid\='' then 
if post=='' then 
lLine=pre'--'mid 


if Linenum>1 then outhandle.write(linesep, 0, lLinesep. length) 
outhandle.write(line, 0, line. length) 
catch e=IOException 
say '# error reading or writing file' e.getMessage 
catch RuntimeException 
say '# processing ended' 
finally do == ¢€lose files 
if inhandle\=null then inhandle.close 
if outhandle\=null then outhandle.close 
catch IOException 
-- ignore errors during close 
end 
end lLinenum 
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Flass 22FacilityReport 


® You can set an OutputStream on the RexxlO class (which is static) cheno 
yee 
® For the first time, you can switch between stdout and stderr * Default constructor 
: method ZzFacilityReport() 
® You may also specify a FileOutputStream return 
method mainCargs-String[]) static 
® All say output from that moment on will go to that file EAE Le) 
RexxI0, setOutputStream(FileOutputStream(' fiscfac.csv')) 
® Reset it by setting it back to System.out RexxI0().File('data/erp_nb_dpsob_bp_acc. txt"). forEachline(z.FiletC)) 


RexxI0().File('data/pri_zzfacility. txt"). forEachline(z. file2Q) 


class ZzFacilityReport.filet dependent implements LineHandler 








i thod hi 
® Every say always flushes the output stream (and always did) eeaes te Tres oboe 
parent. bpSet.add(bp. strip) 
® Even when this is taken into account: class ZzFacilityReport.filez dependent implements LineHandler 


method handleCin) 
Z , z = 2zFacilityQ) 
® On systems with slow consoles (read: windows): z.parseCin) 
if z.getPARTNER = '' then return 





if parent.bpSet.contains(z.getPARTNER. strip) then return 


® The speedup is stunning when writing to a file {f Z.getPARTNER = 'PARTNER’ then return ‘ H 
if z.getZZACTVTSTART = '' then z,setZZACTVTSTART('01.01.1900') 


FIGURE 3: Set the output stream for Say 


s) say Linenum-1 'lines written' 
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What if we want some say output going 


Comanle)comelulnelulesiiccrclantows 





@ To make say output go to more streams (stdout, a file, stderr) we can: 


® pushOutputStream 
© Add one outputstream 
® popOutputStream 


® Remove the latest added outputstream 


® StdOut in RexxlO is now a ConcurrentLinkedDeque 


© Which should make it reasonable thread safe 


method setOutputStream(out=OutputStream) static 
StdOut.clear(Q) 
StdOut.push(PrintWriter(Cout)) 


method pushOutputStreamCout=OutputStream) static 
StdOut.push(PrintWriterCout)) 


method popOutputStream() static 
do 
StdOut .pop() 
catch java.util .NoSuchElLementException 
StdOut. push(PrintWriter(System.out)) 
end 


FIGURE 4: Using more outputstreams 
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Algorithms in NetRExx 


14.1 Factorial 


A factorial is the product of an integer and all the integers below it; the mathemati- 
cal symbol used is ! (the exclamation mark). For example 4! is equal to 24 (because 
4*3*2*1=24). The following program illustrates a recursive (a method calling itself) and 
an iterative approach to calculating factorials. 


Listing 14.1: Factorial 


/x NetRexx ,/ 


options replace format comments java symbols nobinary 


numeric digits 64 -- switch to exponential format when numbers become larger than 64 
digits 
say 'Input a number: \-' 
say 
do 
n_ = long ask -- Gets the number, must be an integer 
say n_'! =' factorial(n_) '(using iteration) ' 
say n_'! =' factorial(n_, 'r') '(using recursion) ' 


catch ex = Exception 
ex.printStackTrace 
end 


return 


method factorial(n_ = long, fmethod = 'I') public static returns Rexx signals 
IllegalArgumentException 


if n_ < © then - 
signal IllegalArgumentException('Sorry, but' n_ 'is not a positive integer') 


select 
when fmethod.upper = 'R! then - 
fact = factorialRecursive(n_) 


otherwise -— 
fact = factorialIterative(n_) 
end 


return fact 


method factorialIterative(n_ = long) private static returns Rexx 


fact = 1 

loop i_ = 1 to n_ 
fact = fact , iL 
end i_ 


return fact 


method factorialRecursive(n_ = long) private static returns Rexx 
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if n_ > 1 then - 

fact = n_ yx factorialRecursive(n_ - 1) 
else - 

fact = 1 


return fact 
Executing this program yields the following result: 


===== Exec: RCFactorial ===== 

Input a number: 

42 

42! 1405006117752879898543142606244511569936384000000000 (using iteration) 
42! = 1405006117752879898543142606244511569936384000000000 (using recursion) 


As you can see, fortunately, both approaches come to the same conclusion about the 
results. In the above program, both approaches are a bit intermingled; for more clarity 
about how to use recursion, have a look at this: 


Listing 14.2: Factorial Recursive 


class Factorial 
numeric digits 64 


method main(args=String[]) static 
say factorial_(42) 


method factorial_(number) static 
if number = © then return 1 
else return number , factorial_(number-1) 


In this program we can clearly see that the factorial_ method, that takes an argument 
number (which is of type RExx if we do not specify it to be another type), calls itself in 
the method body. This means that at runtime, another copy of it is run, with as argument 
number that the first invocation returns (the result of 42*41), and so on. 


In general, a recursive algorithm is considered more elegant, while an iterative approach 
has a better runtime performance. Some language environments are optimized for re- 
cursion, which means that their processors can spot a recursive algorithm and optimize 
it by not making many useless copies of the code. Some day in the near future the JVM 
will be such an environment. Also, for some problems, for example the processing of 
tree structures, using a recursive algorithm seems much more natural, while an iterative 
algorithm seems complicated or forced. 


14.2 Fibonacci 


Listing 14.3: Fibonacci 


/x NetRexx ,/ 
options replace format comments java symbols 


numeric digits 210000 /xprepare for some big ones. ,/ 
parse arg xy. /xallow a single number or range.,/ 
if x == '' then do /x%no input? Then assume -30-->+30,/ 
x = -30 

¥ =X 

end 

if y == '' then y = x /xif only one number, show fib(n),/ 
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loop k = x to y /xprocess each Fibonacci request.,/ 
q = fib(k) 

w = q. length /xif wider than 25 bytes, tell it,/ 
say 'Fibonacci' k"="q 

if w > 25 then say 'Fibonacci' k "has a length of" w 

end k 

exit 


pana ne Sa Sas SSS 8 eS FIB subroutine (non-recursive)---,/ 
method fib(arg) private static 

parse arg n 

na = n.abs 


if na < 2 then return na /xhandle special cases. ,/ 
a=0 

b=1 

2 to na 


loop j = 


Ss = 
ae 
b = 
end 


uno 


if n>oO  |na// 2 == 1 then return s /,if positive or odd negative... ,/ 
else return -s /y,return a negative Fib number. ,/ 


47 


48 


er a 


15 





Using Parse 


The Parse statement is one of the stalwarts of the Rexx family of languages, and allows 
one to easily split a string into parts without needing to resort to more traditional tech- 
niques of string processing. 


The syntax of a parse statement is 
parse term template 


where termis a string or a previously initialised variable. The template is a list of instruc- 
tions describing how to split the string. 


15.1 Literal Parsing 


The most common use of parse is to split a string up into parts separated with a delimiter 
- whilst the most common delimiter is a simple space any string may be used:- 


Listing 15.1: Simple Parse Example 


log = "2014/05/15 21:35:47.012 - error in {{[findit]}}" 

parse log year "/" month "/" day hour ":" minute ":'" second "." msecond "-" text 

say "On day" day "of month" month "at about" hour":"minute "we got" text 

parse text "{{[" name "]}}" 

say name 

Here log is composed of a datestamp separated from a message by a hyphen. The dates- 
tamp is composed of a date separated from a time by a space - within the date the year 
month and day are delimited by a slash and within the date the hour, minute and second 
fields by a colon. The millisecond field is separated from the seconds by a decimal point. 
The first parse divides these using the relevant delimiter - where there is no delimiter 
then a space is used. 


The term is the variable log and the template is 
year ”/” month ”/” day hour ”:” minute ”:” second ”.” msecond ”-” text 
This first template may be read as the following sequence of actions 


. Assign the contents of log to the variable year until a / is encountered (2014) 
. Following the / assign month with the sting found up until another / (05) 
. Place the contents following the / until a space into the variable day (15) 


RwN eB 


. Following the space, assign the value found up until the : into the hour variable 
(21) 


5. Repeat for the variable minute (35) 
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6. Assign the second value up until the . 
7. Take the value for msecond until a delimiter of - is seen 
8. Assign the remainder to variable text 


The second parse statement shows how the delimiters can be more complex - the 
template is 


aa ef [7 name | }}” 


and extracts the value between {{[ and ]}} to the variable (name) 


Running the above example will produce the following output:- 


At about 21:35 we got error in {{[findit]}} 
findit 


As another example, consider 


Listing 15.2: Parse Word-Split Example 


quote = "Now is the winter of our discontent" 
loop forever 

parse quote word quote 

say word 

if quote = "" then leave 
end 


This will take the first word from quote, and assign the remainder back into quote, print 
the word taken and repeat until the variable quote is the empty string. The output from 
this will be 

Now 

is 

the 

winter 

of 

our 

discontent 


15.1.1 The Placeholder (dummy) Variable 


The first example assigns values to several variables that are not used - this is unnecessary 
and can be avoided by the use of a placeholder variable which is the . character. 


If this is done, the first parse statement becomes 
parse log . ”/” month ”/” day hour ”:” minute ”:” . 7.” . %-” text 


The output will remain the same. 


15.2 Positional Parsing 


Whilst the majority of parsing can be done using a fixed literal delimiter, the parse in- 
struction also allows parsing based on positional patterns. This is achieved with the use 
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of numerical values in the template - the values may also take a prefix of +, - or = 


no prefix or = indicates that the number is an absolute column value in the string be- 
ing parsed 

+ indicates a relative position that starts from the specified position after the position 
where the last match occurred 

- indicates a relative position that starts from the specified position before the last match 


These points are best illustrated by example 


Listing 15.3: Positional Parsing 


quote = "Now is the winter of our discontent" 
tens = " LITT 2 2s 2335353" 
units = "12345678901234567890123456789012345" 
say quote 

say tens 

say units 


parse quote 10 strl1 20 -8 str2 +6 str3 

-- strl starts at column 10 and is 10 chars long 

say str1 "("str1.length")" 

-- str2 steps back 8 chars and is 6 chars long 

say str2 "("str2.length")" 

-- str3 is the remainder of the string (as should be expected) 
say str3 


Running this gives the following 


Now is the winter of our discontent 
11111111112222222222333333 
12345678901234567890123456 789012345 
e winter o (10) 
winter (6) 
of our discontent 


Both literal and positional parsing can be combined. Keen-eyed readers will have 
noted that the output from the first example contained an extra space before the word 
error 


At about 21:35 we got error in {{[findit]}} 
Extra space here ws 


This is the result of assigning the remainder of the string to the variable text - leading 
blanks are normally removed except in this special case. 


One can use a positional pattern to eliminate this extra space:- 


Listing 15.4: Combined Parsing 


log = "2014/05/15 21:35:47.012 - error in {{[findit]}}" 

parse log . "/" month "/" day hour ":" minute ":" 2 "J". "=" +2 text 
say "On day" day "of month" month "at about" hour":"minute "we got" text 
parse text "{{[" name "]}}" 

say name 


Note that the relative positional pattern used here is +2 - 0 is the position of the last 
match which is the hyphen, +1 is the position of the following space and thus +2 is the 
start of the target string. 
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15.3. Variable Templates 


Variables may be used as the pattern in the templates in order to accommodate the 
occasions when the pattern may need to be specified at runtime. An illustration of this 
is the following evolution of the first example that will correctly parse dates specified in 
two distinct ways 


Listing 15.5: Variables in Patterns 


log me 
log[1] = "2014/05/15 21:35:47.012 - error in {{[findit]}}" 


log[2] "2014-05-15 21:35:47.012 - error in {{[findit]}}" 
loop i = 1 to 2 
dtsep = log[i].substr(5,1) 
parse log[i] . (dtsep) month (dtsep) day hour ":" minute ":" 2 "J." . "=" +2 text 


say "On day" day "of month" month "at about" hour":"minute "we got" text 
end 


Note that he date separator dtsep is determined and then used in the parse pattern by 
enclosing it in parentheses, thus (dtsep). The output of this program is 


On day 15 of month 05 at about 21:35 we got error in {{[findit] }} 
On day 15 of month 05 at about 21:35 we got error in {{[findit] }} 


It can be seen that the date was successfully parsed in both cases. 


It is important to note that any pattern specified by a variable will be assumed to be literal 
unless it has a +, - or = prefix. Should one wish to use positional patterns then the prefix 
must be used. 


Listing 15.6: Variables in Positional Patterns 


message = "this is a message that contains the number 10- just there, see?" 
pat = "jo" 

parse message partl 5 (pat) part2 

say "Literal:" partl part2 

parse message partl 5 =(pat) part2 

say "positional:" partl part2 


When run this illustrates the difference between the two parse statements 


literal: this - just there, see? 
positional: this message that contains the number 10- just there, see? 
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Using Trace 


The trace command is the inbuilt debugging facility of the RExx family, and, as might be 
expected from its name, allows one to trace the execution of your program. It is possible 
to trace both program statements and the state of variables within your code. 


(Trace) is a compile-time option, and should be disabled once debugging as been com- 
pleted. 


The syntax of the trace command is 
trace traceitem 


where traceitem defines the behaviour of the trace command. Only one traceitem 
may be given, and only one of the program statement tracing options will be in use at 
any time. Variable tracing options, however, are additive and such statements may appear 
multiple times. 


All trace output is headed by three hyphens followed by the source file name, as follows 


--- TerribleExample.nrx 


16.1 Tracing Program Statements 


The traceoptions that affect the tracing of program statements are 


all will display all statements as they are executed. Each line in the trace output will be 
prefixed with x= or a x-* should output span subsequent lines. 
The trace all statement can be placed anywhere in the program source. 

methods will show the each method as it is invoked, along with any parameters to it. 
The trace output for method traces is prefixed by a x=* for the method call itself 
and a >a> indicating the assignment of a value to a method parameter. No other 
program statements will be traced. 
The trace methods statement should be placed before the first method is defined 
in a class. 

results acts as though the trace all statement had been given, and, if placed before any 
method will also act as though trace methods was also specified. 
In addition to the all and methods tracing implied by results the following will 
also take place 
Properties will have their assignments shown. These will be identified by >p> 
Local variables will also be traced, with assignments identified by >v> 
Expressions will have their evaluations shown if not shown for as a part of properties 

or local variable trace output. Such evaluations are indicated by »> 
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off trace off disables tracing. No further tracing output will take place. 


16.2 Tracing Variables 


The all-or-nothing tracing offered by, for instance trace results can lead to a deluge 
of trace information in many cases. 


In these instances one may more finely control which variables one wishes to monitor 
using the trace var statement. The syntax of the trace var statement is 

trace var varl [var2...] 

or 


trace var -varl [-var2...] 


where the first form adds variables to the list that should be watched, and the second 
removes them. The forms may be mixed to add some variables and remove others si- 
multaneously, as here:- 


trace var varl -var2 var3 -var4 -var5 

to monitor var1 and var3 and remove var2, var5 and var5 from the list of watched 
variables. 

Multiple trace var statements may be used, as mentioned above. 

It is not an error to specify a variable name that does not exist. 

Each variable can appear only once in a trace statement. 

A variable name may that of any type - including arrays (without the []). 


Program tracing options never alter the list of watched variables. If tracing has previ- 
ously been turned off then variable tracing may be resumed simply with a trace var 
statement. 


16.3 Examples 


16.3.1 Program Trace 


Trace All 


Running the program below 


Listing 16.1: Trace Example 1 


trace all 
class traceExample 
properties 
aIs 
bIs 


method traceExample(a, b) 
aIs =a 
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bIs = b 


method times 
retturn aIs y, bIs 


method main($cmdini=String[]) static 
arg=Rexx ($cmdin1) 
te = traceExample(2, 3) 
fred = te.times 
say fred 


gives trace output of 


--- traceExample.nrx 
16 *=* method main(Scmdini=String[]) static 
>a> Scmdinl ”[Ljava.lang.String;@72ebbf5c” 
17 «=x arg=Rexx ($cmdin1) 
18 x= te = traceExample(2, 3) 
9 *=x method traceExample(a, b) 
>a> a 2” 
>a> b 3” 
10 *=x aIs =a 
11 *=x bIs 
12 *-x 
19 x=x fred = te.times 
13 *=* method times 
14 *x=x return aIs * bIs 


Il 
oO 


20 *x=x say fred 
This output may be read thus 


— traceExample.nrx Identification of the program being traced. This is the tracing 
context. 


16 *=* method main($cmdin1=String| ) static] The first line that is actually executed 
is line 16. 


>a> $cmdin1 ”[Ljava.lang.String;@72ebbf5c” Variable $cmdin1 is assigned a string 
value from the java virtual machine. 


17 *=* arg=Rexx($cmdin1) Line 17 is executed next... 
18 *=* te = traceExample(2, 3) followed by line 18 
9 *=* method traceExample(a, b) Line 18 is a method call to a method on line 9... 

>a>a”2” which assigns a value of 2 to parameter a 
>a> b 3” anda value of 3 to parameter b 

10 *=* als = a the following lines document only code execution 

11 *=* bIs = b 

12 ++ 

19 *=* fred = te.times 

13 *=* method times 

14 *=* return als * bIs 

20 *=* say fred 
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Trace Methods 


Replacing the trace all from line 1 with trace methods gives trace output of 


16 


13 


x= 
>a> 
x= 
>a> 
>a> 


k=k 


traceExample.nrx 


method main($cmdini=String[]) static 
Scmdinl ”[Ljava.lang.String;@8094cc7” 


method traceExample(a, b) 


a 1” 
b 23:3 ” 
method times 


As should be expected, this is a subset of the output provided when using trace all. 


Trace Results 


Replacing the trace all from line 1 with trace results would give 
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17 


18 


10 


11 
12 
11 
18 
19 
13 
14 


19 
20 


k= 
>a> 
k= 
>>> 
>v> 
k= 
>>> 
>>> 
k= 
>a> 
>a> 
k= 
>p> 
k= 
xk 
>p> 
>v> 
k= 
k= 
k= 
>>> 
>v> 
k= 


>>> 


traceExample.nrx 


method main($cmdini=String[]) static 
Scmdinl ”[Ljava.lang.String;@72ebbf5c” 


arg=Rexx ($cmdin1) 
”TLjava. Lang.String;@72ebbf5c” 
arg 9999 

te = traceExample(2, 3) 
9? 
273? 
method traceExample(a, b) 
a 79” 
b ” 3” 

aIs =a 
a a Ss ae? J ” 

bIs = b 
b aN Ss 2253 9 
te "traceExample@53606bf5” 


fred = te.times 
method times 
return alIs * bIs 
6” 
fred ”6” 
say fred 
6” 


Here is can be seen that more information is available. Noticeably, the values of assign- 
ments are given. For instance 


Line 17 now has an entry of >v> arg 


set to the empty string 


3999 


showing that hte value of the variable arg was 
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Line 18 now has the values of the specified parameters evaluated (»>”2” and »» ”3”) 

Lines 10 and 11 show that values were assigned to parameters (>p> als ”2” and >p> bls ”3”) 

Line 18 then shows the assignment of the instantiated class to variable te 

Line 14 shows the evaluation of the multiplication (»> ”6”), which is assigned to vari- 
able fred in line 19 (>v> fred 6”) on line 19. 

Finally we see the evaluation of variable fred on line 20. 


16.3.2 Variable Tracing 


Consider the following example:- 


Listing 16.2: Trace Example 2 


a = "a" 
b = "bp" 

c=1 

d=2 

e=3 

trace varabcdefy 
z=a||b 

y=ctd 

f=y+2 

e= f 

trace var -a -c -d -e 
yrykx 

a=y 

e=a 


Running this will produce the output below 


--- variableTraceExampLle.nrx 


9 x*=k y=ctd 
>v> y 73” 

10 *=* f =y +2 
>v> Ff 75” 

11 *=x e = f 
>v> e 75” 

14 *=x y =y * 2 
>v> y 6” 


It can be seen that only the lines that contain watched variables are traced. This the vari- 
able assignments on lines 9, 10 and 11 are displayed, since the variables being watched 
from line 7 to line 12 area, b, c, d, e, fandy. 


Following this, however only the assignment to variable y is shown, since the variables a, 
b ,c dandeare removed from the list with the command trace var -a -c -d -e. 


16.4 Tracing Notes 


One further prefix may be encountered in the trace outout +++ which signifies an error. 


Whenever tracing transfers to a different source file, anew tracing context, identified 
by the — prefix is output. 
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Tracing is expensive, and may dramatically impact the run-time performance of the pro- 
gram being traced. Judicious use may therefore be warranted. 
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Concurrency 


17.1 Threads 


Threads are a built-in multitasking feature of the JVM. Where earlier JVM implemen- 
tations sometime ran on so-called Green Threads, which is a library that implements 
thread support for OS’ses that do not have this facility (an early version of Java was called 
GreenTalk for this reason), modern versions all use native OS thread support. 


A new thread is created when we create an instance of the Thread class. We cannot tell a 
thread which method to run, because threads are not references to methods. Instead we 
use the Runnable interface to create an object that contains the run method: 


Every thread begins its concurrent life by executing the run method. The run method 
does not have any parameters, does not return a value, and is not allowed to signal any 
exceptions. Any class that implements the Runnable interface can serve as a target of 
a new thread. An object of a class that implements the Runnable interface is used as a 
parameter for the thread constructor. 


Threads can be given a name that is visible when listing the threads in your system. It is 
good practice to name every thread, because if something goes wrong you can see which 
threads are still running. Additionally, threads are grouped by thread groups. If you do 
not supply a thread group, the new thread is added to the thread group of the currently 
executing thread. The threads of a group and their subgroups can be destroyed, stopped, 
resumed, or suspended by using the ThreadGroup object. 


The next two samples are used in the following programs that illustrate thread usage. 


Listing 17.1: Thread sample 1 


/y thread/ThrdTsti.nrx ,/ 


hl 
h2 


= Hellol('This is thread 1') 
= Hellol('This is thread 2') 
Thread(h1,'Thread Test Thread 1').start() 
Thread(h2,'Thread Test Thread 2').start() 


class Hellol implements Runnable 
Properties inheritable 
message = String 


method Hellol( s = String) 
message = Ss 


method run() 
loop for 50 
say message 
end 
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Listing 17.2: Thread sample 2 


/y thread/ThrdTst2.nrx ,/ 


hl 
h2 


Hello2('This is thread 1') 
Hello2('This is thread 2') 


hl.start() 
h2.start() 


class Hello2 extends Thread 
Properties inheritable 
message = String 


method Hello2( s = String) 
super('Thread Test - Message' s) 
message = Ss 


method run() 
loop for 50 
say message 
do 
sleep(10) 
catch InterruptedException 
end 
end 


The second class, Hello2, does not implement the Runnabte interface, but subclasses it, so 
it inherits its methods. This is a valid approach, and it is up to the developer to choose an 
implementation and worry about the semantics of an inherited thread interface. A newly 
created thread remains idle until the start method is invoked. The thread then wakes up 
and executes the run method of its target object. The start method can be called only 
once. The thread continues running until the run method completes or the stop method 
of the thread is called. 
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User Interfaces 


18.1 AWT 


18.2 Web Applets using AWT 


Web applets can be written one of two styles: 


¢ Lean and mean, where binary arithmetic is used, and only core Java classes (such 
as java.lang.String) are used. This is recommended for optimizing webpages which 
may be accessed by people using a slow internet connection. Several examples using 
this style are included in the NetRexx package like the two listed below. 


Listing 18.1: Nervous Texxt 


1 /y NervousText applet in NetRexx: Test of text animation. 


2 Algorithms, names, etc. are directly from the Java version by 
3 Daniel Wyszynski and kwalrath, 1995 
4 x/ 


5 options binary 
6 
7 class NervousTexxt extends Applet implements Runnable 


9 separated = char[] 

1 $S§ = String 

u killme = Thread 

2  threadSuspended = boolean 0 


14 ©=60method init 

15 resize(300,50) 

16 setFont(Font("TimesRoman", Font.BOLD, 30)) 
7 s = getParameter ("text") 

18 if s = null then s = "NetRexx" 


20 separated = char[s. length] 
21 s.getChars(0, s.length, separated, 0) 


23 method start 

24 if killme \= null then return 
25 killme = Thread(this) 

26 killme.start 


28 method stop 
29 killme = null 


31 method run 
32 loop while killme \= null 


33 Thread.sleep(100) 

34 this.repaint 

35 catch InterruptedException 
36 end 


37 killme = null 


39 method paint(g=Graphics) 
40 loop i1=0 to s.length-1 
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41 x_coord = int Math. random,10+154,7 


2 y_coord = int Math. random,10+36 
43 g.drawChars(separated, i, 1, x_coord, y_coord) 
44 end 


44 method mouseDown(evt=Event, x=int, y=int) returns boolean 


47 if threadSuspended then killme.resume 
48 else killme.suspend 

49 threadSuspended = \threadSuspended 

50 return 1 


Listing 18.2: ArchText 


1 /y ArchText applet: multi-coloured text on a white background ,/ 
2 /% Mike Cowlishaw April 1996, December 1996 oe | 


3 options binary 
4 


5s class ArchText extends Applet implements Runnable 


6 

7 text ="NetRexx" /x default text ,/ 
s tick =0 /y% display counter ,/ 
9 timer =Thread null /» timer thread ,/ 
10 shadow=Image /x% shadow image ,/ 
u draw =Graphics /»% where we can draw ,/ 


13 method init 

4 s=getParameter ("text") /% get any provided text ,/ 

i if s\=null then text=s 

1s Shadow=createImage(getSize.width, getSize.height) /, image ,/ 
wv  draw=shadow. getGraphics 

is draw.setColor(Color.white) /x background ,/ 

1 «draw. fillRect(0, 0, getSize.width, getSize.height) /, .. x/ 
2 draw.setFont(Font("TimesRoman", Font.BOLD, 30)) /, font ,/ 


2 method start 
2 «if timer=null then timer=Thread(this) /, new thread ,/ 
2 timer.setPriority(Thread.MAX_PRIORITY) /, time matters ,/ 


2 timer.start /x start the thread ,/ 
26 

27 method stop 

2 «6if timer=null then return /x have no thread ,/ 
2 «=6timer.stop /x else stop it x/ 
30 timer=null fx «se and discard +/ 
31 

32. method run /x this runs as thread ,/ 
33 Loop while timer\=null 

34 tick=tick+1 /* next update ,/ 


35 hue=((tick+133)//191)/191 
36 draw.setColor(Color.getHSBColor(hue, 1, 0.7)) 
37 draw.drawString(text, 0, 30) 


38 this.repaint /x «. and redraw ,/ 
39 Thread. sleep(119) /x% wait awhile ,/ 
40 catch InterruptedException 

4. end 

ga  timer=null /x discard 4/ 


44 method update(g=Graphics) /, override Applet's update ,/ 
5 paint(g) /x% method to avoid flicker ,/ 


» 


47 method paint(g=Graphics) 

4a g.drawlmage(shadow, 0, 0, null) 

¢ Full-function, where decimal arithmetic is used, and advantage is taken of the full 
power of the NetRexx runtime Rexx class. 
An example using this style is the below WordClock.nrx. 


Listing 18.3: WordClock 


1 /y WordClock -- an applet that shows the time in English. ,/ 
21 x/ 
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/x Parameters: 


/x x/ 
lx face -- the font face to use ged 
ree size -- the font size to use ye 
lx x/ 
ee 


/% Based on the ancient QTIME.REXX, and typical Java applets. ,/ 


class WordClock extends Applet implements Runnable 


timer=Thread null 
offsetx; offsety 
now 


method init 


/y% the timer thread ,/ 
/% text position ,;/ 
/% current time ,;/ 


/x Get parameters from the <applet> markup ,/ 
face=getParameter ("face") /% font face ,/ 
if face=null then face="TimesRoman" 
size=getParameter ("size") 

if size=null then size="20" /x font size ,/ 


setFont(Font(face, Font 
resize(size,20, size,2) 
offsetx=size/2 
offsety=size,3/2 


parse Date() ... now. 


method start 


-BOLD, size) ) 
/x set window size ,/ 
/x and where text will start ,/ 
/x% note Y is from top ,/ 
/x initial time is fourth word ,;/ 


if timer=null then timer=Thread(this) /, new thread ,/ 
timer.setPriority(Thread.MAX_PRIORITY) /, time matters ,/ 


timer.start 


method stop 

if timer\=null then do 
timer.stop 
timer=null 
end 


method run 


/»% start the thread ,/ 


/» have thread ,/ 
fe ae SO StOD TE yf 
jx sv and discard y/ 


/x Use the Java Date class to get the time ,/ 


loop while timer\=null 


parse Date() . .. now. /, time is fourth word ,/ 


this.repaint 
parse now ':' ':'secs 


/x redisplay ,/ 
/% where in minute ,/ 


wait=30-secs /x calculate delay in seconds ,/ 

if wait<=0 then wait=wait+60 

/x say 'secs, wait:' secs wait ,/ 

Thread.sleep(1000,wait) /, wait for milliseconds ,/ 
catch InterruptedException 


say 'Interrupted...' 
end 
timer=null 


method paint(g=Graphics) 


g.drawString(wordtime(now), offsetx, offsety) /, show it ,/ 


/x done ,/ 


/% WORDTIME -- a cut-down version of QTIME.REXX 
Argl is the time string (hh:mm:ss) 
Returns the time in english, as a Rexx string 


«/ 


method wordtime(arg) static returns Rexx 


/x Extract the hours, minutes, and seconds from the time. ,/ 


parse arg hour':'min':'sec 
if sec>29 then min=min+1 /* round up minutes ,/ 


/x Nearness phrases - this time using an array ,/ 


near=Rexx[5] 
near[0]='' 


/x five items ,/ 
/x exact ,/ 


near[1]=' just gone'; near[2]=' just after' /, after ,/ 


near[3]=' nearly'; near 


[4]=' almost' /, before ,/ 


mod=min//5 /% where we are in 5 minute bracket ,/ 


out="It's"near [mod] 


/x Start building the result ,/ 
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7 if min>32 then hour=hour+1 /y, we are TO the hour... ,/ 

7 min=mint2 /, shift minutes to straddle a 5-minute point ,/ 

78 

77  /y Now special-case the result for Noon and Midnight hours ,/ 
so if hour//12=0 & min//60<=4 then do 


81 if hour=12 then return out 'Noon.' 

82 return 'Midnight.' 

83 end 

84 

8 = min=min-(min//5) /x find nearest 5 mins ,/ 

ss if hour>12 

87 then hour=hour-12 /% get rid of 24-hour clock ,/ 
88 else 

89 if hour=0 then hour=12 /, .. and allow for midnight ,/ 


90 
9 /y Determine the phrase to use for each 5-minute segment ,/ 
9 select 


93 when min=0 then nop /y add "o'clock" later ,/ 
94 when min=60 then min=0 /y Gitte ./ 
95 when min= 5 then out=out 'five past' 

96 when min=10 then out=out 'ten past' 

97 when min=15 then out=out 'a quarter past' 

98 when min=20 then out=out 'twenty past! 

99 when min=25 then out=out 'twenty-five past' 

100 when min=30 then out=out 'half past' 

101 when min=35 then out=out 'twenty-five to' 

102 when min=40 then out=out 'twenty to' 

103 when min=45 then out=out 'a quarter to! 

104 when min=50 then out=out 'ten to' 

105 when min=55 then out=out 'five to' 

106 end 


107 
18 numbers='one two three four five six'- /, continuation ,/ 


109 "seven eight nine ten eleven twelve ' 

uo out=out numbers.word(hour) /, add the hour number ,/ 

mum if min=0 then out=out "o'clock" /, .. and o'clock if exact ,/ 
112 

uz return out'.' /»% return the final result ,/ 


114 
us /y Mike Cowlishaw, December 1979 - January 1985. ,/ 
us /y NetRexx version March 1996; applet April 1996. ,/ 


If you write applets which use the NetRexx runtime (or any other Java classes that might 
not be on the client browser), the rest of this section may help in setting up your Web 
server. 


A good way of setting up an HTTP (Web) server for this is to keep all your applets in 
one subdirectory. You can then make the NetRexx runtime classes (that is, the classes 
in the package known to the Java Virtual Machine as netrexx.lang) available to all the 
applets by unzipping NetRexxR jar into a subdirectory netrexx/lang below your applets 
directory. 

For example, if the root of your server data tree is 


D:\mydata 

you might put your applets into 

D:\mydata\applets 

and then the NetRexx classes (unzipped from NetRexxR.jar) should be in the directory 
D:\mydata\applets\netrexx\ lang 


The same principle is applied if you have any other non-core Java packages that you want 
to make available to your applets: the classes in a package called iris.sort.quicksorts would 
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go in a subdirectory below applets called iris/sort/quicksorts, for example. 


Note that since Java 1.1 or later it is possible to use the classes direct from the Net- 
RexxR jar file. 


18.3 Swing 


Swing is the most commonly used name for the second attempt from the SUN engineers 
to provide a graphical user interface library for the JVM. With AWT also acknowledged 
by SUN to be a quick attempt that was made just before release of the first Java package, 
it became clear that it was rather taxing on system resources without compensation by a 
pretty look. A case in point is the event mechanism, that indiscriminately sends around 
mouse and keyboard events even when nobody is listening to them. The architecture for 
Swing prescribes registering for events before they are produced, and tries to have the 
drawing done by the Java graphics engine instead of leaning heavily on the operating 
system's native GUI functionality. The user interface widgets that are produced by Java 
are called light’ and their looks can be changed by applying different skins, called ‘look- 
and-feel’ (LAF) libraries. 


In the first months of its existence Swing gathered quite a bad reputation because it made 
the Java 1.2 releases that contained it very slow in starting up programs that used the li- 
brary. Consequently, much was invested in performance studies by SUN engineers and 
these problems were solved. One of the things that came out is that dividing the libraries 
in a great many classes, done for performance reasons, worked counterproductive. All 
these problems were solved over the years, and developments in hardware and multi- 
threading took care of the rest, and nowadays Swing is a valid way of producing a rich 
client user interface. 


For esthetical reasons, it is best to research a bit in the third party look-and-feel libraries 
that can be obtained. Swing can be made to look beautiful, but it takes some care and 
the defaults are not helping. 


18.3.1 Creating NetRexx Swing interfaces with NetBeans 


18.4 Web Frameworks 


18.4.1 JSF 
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Network Programming 


19.1 Using Uniform Resource Locators (URL) 
19.2. TCP/IP Socket I/O 


19.3. RMI: Remote Method Interface 


67 


68 


tb 
sd 


w 
3 


35 


43 


20 





Database Connectivity with JDBC 


For interfacing with Relational Database Management Systems (RDBMS) NetRExx uses 
the Java Data Base Connectivity (JDBC) model. This means that all important database 
systems, for which a JDBC driver has been made available, can be used from your 
NetRexx program. ‘This is a large bonus when we compare this to the other open source 
scripting languages, that have been made go by with specific, nonstandard solutions 
and special drivers. In contrast, NetRExx programs can be made compatible with most 
database systems that use standard SQL, and, with some planning and care, can switch 
database implementations at will. 





Listing 20.1: A JDBC Query example 


/x jdbc\JdbcQry.nrx 


This NetRexx program demonstrate DB2 query using the JDBC API. 
Usage: Java JdbcQry [<DB-URL>] [<userprefix>] ,/ 


import java.sql. 


parse arg url prefix -- process arguments 
if url = '' then 
url = 'jdbc:db2:sample' 
else do -- check for correct URL 
parse url pl ':' p2 ':' rest 
if pl \= 'jdbc' | p2 \= 'db2' | rest = '' then do 
say 'Usage: java JdbcQry [<DB-URL>] [<userprefix>]' 
exit 8 
end 
end 
if prefix = '' then prefix = 'userid' 
do -- loading DB2 support 


say ‘Loading DB2 driver classes...' 

Class. forName('COM.ibm.db2.jdbc.app.DB2Driver') .newInstance() 

-- Class. forName('COM.ibm.db2.jdbc.net.DB2Driver') .newInstance() 
catch el = Exception 

say 'The DB2 driver classes could not be found and loaded !' 

say 'Exception (' el ') caught : \n' el.getMessage() 


exit 1 
end -- end : loading DB2 support 
do -- connecting to DB2 host 
say ‘Connecting to:' url 
jdbcCon = Connection DriverManager.getConnection(url, ‘userid', 'password') 


catch e2 = SQLException 
say 'SQLException(s) caught while connecting !' 
loop while (e2 \= null) 
say 'SQLState:' e2.getSQLState() 


say 'Message: ' e2.getMessage() 
say 'Vendor: ' e2.getErrorCode() 
say 
e2 = e2.getNextException() 
end 
exit 1 
end -- end : connecting to DB2 host 
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do -- get list of departments with the managers 
say 'Creating query...' 
query = 'SELECT deptno, deptname, lastname, firstnme' - 
"FROM' prefix'.DEPARTMENT dep,!' prefix'.EMPLOYEE emp'- 
"WHERE dep.mgrno=emp.empno ORDER BY dep.deptno' 
stmt = Statement jdbcCon.createStatement () 
say 'Executing query:' 
loop i=0 to (query. length()-1)%75 
say ' ' query.substr(i,75+1,75) 
end 
rs = ResultSet stmt.executeQuery (query) 
say 'Results:' 
loop row=0 while rs.next() 
say rs.getString('deptno') rs.getString('deptname') - 
‘is directed by' rs.getString('lastname') rs.getString('firstnme') 


end 

rs.close() -- close the ResultSet 
stmt.close() -- close the Statement 
jdbcCon.close() -- close the Connection 


say 'Retrieved' row 'departments.' 
catch e3 = SQLException 
say 'SQLException(s) caught !' 
loop while (e3 \= null) 
say 'SQLState:' e3.getSQLState() 


say 'Message: ' e3.getMessage() 
say 'Vendor: ' e3.getErrorCode() 
say 
e3 = e3.getNextException() 
end 
end -- end: get list of departments 


The first peculiarity of JDBC is the way the driver class is loaded. When most classes are 
pulled in’ by the translator, a JDBC driver traditionally is loaded through the reflection 
API. This happens in line 22 with the Class. forName call. This implies that the library 
containing this class must be on the classpath. 


In previous versions of JDBC, to obtain a connection, one first had to initialize the JDBC 
driver by calling the method Class.forName. Any JDBC 4.0 drivers that are found on the 
class path are automatically loaded. (However, one must manually load any drivers prior 
to JDBC 4.0 with the method Class.forName.) 


In line 32 of the example we connect to the database using a url and a userid/password 
combination. This is an easy way to do and test, but for most serious applications we 
do not want plaintext userids and passwords in the sourcecode, so most of the time we 
would store the connection info in a file that we store in encrypted form, or we use 
facilities of J2EE containers that can provide data sources that take care of this, while 
at the same time decoupling your application source from the infrastructure that it will 
run on. 


In line 47 the query is composed by filling in variables in a Rexx string and making 
a Statement out of it, in line 50. In line 55, the Statement is executed, which yields 
a ResultSet. This has a cursor that moves forward with each next call. The next call 
returns true as longs as there are rows from the resultset to return. 


The ResultSet interface implements getter methods for all JDBC Types. In the above 
example, all returned results are of type String. 
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Listing 20.2: A JDBC Update example 


/4. jdbc\JdbcUpd.nrx 


This NetRexx program demonstrate DB2 update using the JDBC API. 
Usage: Java JdbcUpd [<DB-URL>] [<userprefix>] [U] ,/ 


import java.sql. 


parse arg url prefix lLowup -- process arguments 
if url = '' then 
url = 'jdbc:db2:sample' 
else do -- check for correct URL 
parse url pl ':' p2 ':' rest 
if pl \= 'jdbc' | p2 \= 'db2' | rest = '' then do 
say 'Usage: java JdbcUpd [<DB-URL>] [<userprefix>] [U]' 
exit 8 
end 
end 
if prefix = '' then prefix = 'userid' 
if lowup \= 'U' then Lowup = 'L' 
do -- loading DB2 support 


say ‘Loading DB2 driver classes...' 

Class. forName('COM.ibm.db2.jdbc.app.DB2Driver') .newInstance() 

-- Class. forName('COM.ibm.db2.jdbc.net.DB2Driver') .newInstance() 
catch el = Exception 

say 'The DB2 driver classes could not be found and loaded !' 

say 'Exception (' el ') caught : \n' el.getMessage() 


exit 1 
end -- end : loading DB2 support 
do -- connecting to DB2 host 
say ‘Connecting to:' url 
jdbcCon = Connection DriverManager.getConnection(url, '‘userid', 'password') 


catch e2 = SQLException 
say 'SQLException(s) caught while connecting !' 
loop while (e2 \= null) 
say 'SQLState:' e2.getSQLState() 


say 'Message: ' e2.getMessage() 
say ‘Vendor: ' e2.getErrorCode() 
say 
e2 = e2.getNextException() 
end 
exit 1 
end -- end : connecting to DB2 host 
do -- retrieve employee, update firstname 
say ‘Preparing update...' -- prepare UPDATE 


updateQ = 'UPDATE' prefix'.EMPLOYEE SET firstnme = ? WHERE empno = ?! 
updateStmt = PreparedStatement jdbcCon.prepareStatement (updateQ) 

say 'Creating query...' -- create SELECT 

query = 'SELECT firstnme, lastname, empno FROM' prefix'.EMPLOYEE' 
stmt = Statement jdbcCon.createStatement () 


rs = ResultSet stmt.executeQuery(query) -- execute select 
loop row=0 while rs.next() -- loop employees 
firstname = String rs.getString('firstnme') 
if lowup = 'U' then firstname = firstname. toUpperCase() 
else do 
dChar = firstname.charAt(0) 
firstname = dChar || firstname.substring(1).toLowerCase() 
end 
updateStmt.setString(1, firstname) -- parms for update 


updateStmt.setString(2, rs.getString('empno')) 
say 'Updating' rs.getString('lastname') firstname ': \0' 


say updateStmt.executeUpdate() 'row(s) updated' -- execute update 
end 
rs.close() -- close the ResultSet 
stmt.close() -- close the Statement 
updateStmt.close() -- close the PreparedStatement 
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jdbcCon.close() -- close the Connection 
say 'Updated' row 'employees.' 
catch e3 = SQLException 
say 'SQLException(s) caught !' 
loop while (e3 \= null) 
say 'SQLState:' e3.getSQLState() 


say 'Message: ' e3.getMessage() 
say 'Vendor: ' e3.getErrorCode() 
say 
e3 = e3.getNextException() 
end 
end -- end: empoyees 


For database updates, we connect using the driver in the same way (line 23) and 
now prepare the statement used for the database update (line 50). In this example, 
we loop through the cursor of a select statement and update the row in line 66. The 
executeUpdate method of PreparedStatement returns the number of updated rows as 
an indication of success. 


From JDBC 2.0 on, cursors are updateable (and scrollable, so they can move back and 
forth), so we would not have to go through this effort - but it is a valid example of an 
update statement. 


72 


21 





WebSphere MQ 


WebSphere MQ (also and maybe better known as MQ Series) is IBM’s messaging and 
queing middleware, and is in use at a great many financial institutions and other compa- 
nies. It has, from a programming point of view, two APIs: JMS (Java Messaging Services), 
a generic messaging API for the Java world, and MQI, which is older and proprietary to 
IBM's product. The below examples show the MQI; other examples might show JMS 
applications. 


This is the sample Java application for MQI, translated (and a lot shorter) to NetRexx. 


Listing 21.1: MQ Sample 


1 import com.ibm.mq.MQException 

2 import com. ibm.mq.MQGetMessageOptions 

3 import com. ibm.mq.MQMessage 

4 import com. ibm.mq.MQPutMessageOptions 

s import com. ibm.mq.MQQueue 

6 import com. ibm.mq.MQQueueManager 

7 import com.ibm.mq.constants.MQConstants 
8 

9 class MQSample 

10 properties private 


2 gqManager = "rjtestqm"; 
13 «©qName = "SYSTEM.DEFAULT.LOCAL.QUEUE" 


1 method main(args=String[]) static binary 
16 m = MQSample() 


17 do 

18 say "Connecting to queue manager: " m.qManager 
19 qMgr = MQQueueManager (m. qManager ) 

20 

21 openOptions = MQConstants.MQOO_INPUT_AS_Q_DEF | MQConstants .MQOO_OUTPUT 
22 

23 say "Accessing queue: " m.qName 

24 queue = qMgr.accessQueue(m.qName, openOptions) 
25 

26 msg = MQMessage() 

27 msg.writeUTF("Hello, World!") 

28 

29 pmo = MQPutMessageOptions() 

30 

31 say "Sending a message..." 

32 queue.put(msg, pmo) 

33 

34 rcvMessage = MQMessage() 

35 

36 gmo = MQGetMessageOptions() 

37 

38 say "...and getting the message back again" 

39 queue.get(rcvMessage, gmo) 

40 

41 msgText = rcvMessage.readUTF () 

42 say "The message is: " msgText 

43 

44 say "Closing the queue" 

45 queue.close() 
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say "Disconnecting from the Queue Manager" 
qMgr.disconnect() 
say "Done!" 
catch ex=MQException 
say "A WebSphere MQ Error occured : Completion Code " ex.completionCode "Reason 
Code " ex.reasonCode 
catch ex2=java.io.I0Exception 
say "An IOException occured whilst writing to the message buffer: " ex2 
end 


This sample connects to the Queue Manager (called rjtestqm) in bindings mode, as op- 
posed to client mode. Bindings mode is only a connection possibility for client programs 
that are running in the same OS image as the Queue Manager, on the server. Note that 
the application connects (line 19), accesses a queue (line 23), puts a message (line 32), 
gets it back (line 39) closes the queue (line 45) and disconnects (line 48) all without 
checking returncodes: the exceptionhandler takes care of this, and all irregulaties will be 
reported from the catch MQException block starting at line 50). 


The main method does in this case not follow the canonical form, but has *binary’ as 
an extra option. Option binary can be defined on the command line as an option to 
the translator, as a program option, as a class option and as a method option. Here the 
smallest scope is chosen. There is a good reason to make this method a binary method: 
accessing a queue in MQ Series requires some options that are set using a mask of bi- 
nary flags - this works, in current NetRExx versions, only in binary mode, because the 
operators have other semantics in nobinary mode. 


Listing 21.2: MQ Message Reader 


import com.ibm.mq. 


class MessageReader 
properties private 


qManager = "rjtestqm"; 
qName = "TESTQUEUE1" 


method main(args=String[]) static binary 


m = MessageReader () 

do 
MQEnvironment.hostname = 'Llocalhost' 
MQEnvironment.port = int 1414 
MQEnvironment.channel = 'CHANNEL1' 


-- exit assignment 

exits = TimeoutChannelExit() 
MQEnvironment.channelReceiveExit = exits 
MQEnvironment.channelSendExit = exits 
MQEnvironment.channelSecurityExit = exits 


say "Connecting to QM: " m.qManager 
qMgr = MQQueueManager (m.qManager ) 


openOptions = MQConstants.MQOO_INPUT_AS_Q_DEF 


say "Accessing Queue : " m.qName 
queue = qMgr.accessQueue(m.qName, openOptions) 


gmo = MQGetMessageOptions() -- essential here is that we have MQGMO_WAIT; 
otherwise we cannot timeout 

gmo.Options = MQConstants.MQGMO_WAIT | MQConstants.MQGMO_FAIL_IF_QUIESCING | 
MQConstants .MQGMO_SYNCPOINT 

gmo.WaitInterval = MQConstants.MQWI_UNLIMITED 


loop forever 
rcvMessage = MQMessage() 
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37 queue.get(rcvMessage, gmo) 
38 msgText = rcvMessage.readUTF () 


39 say "Got a message; the message is: " msgText 

40 say 

41 end 

42 

43 catch ex=MQException 

44 say "A WebSphere MQ Error occured : Completion Code " ex.completionCode "Reason 
Code '" ex.reasonCode 

45 say "Closing the queue" 

46 queue.close() 

47 say "Disconnecting from the Queue Manager" 

48 qMgr.disconnect() 

49 say "Done!" 

50 end 


In contrast to the previous sample the MessageReader sample only has one import state- 
ment. This is always hotly debated in project teams, one school likes the succinctness of 
including only the top level import, and only goes deeper when there is ambiguity de- 
tected; another school spells out the all imports to the bitter end. 


The MessageReader sample connects to another queue, called TESTQUEUE] (specified 
in line 7) but here we connect in client mode, as indicated by lines 13-15 which specify 
an MQEnvironment. Other options are using an MQSERVER environment variable or 
a Channel Definition Table. 


This program is also uncommon in that it uses M@Constants .MQGMO_WAIT as an option 
instead of being triggered as a process by a message on a trigger queue. Using this option 
means that the program waits (stays active, not really busy polling but depending on an 
OS event) until a new message arrives, which will be processed immediately. 


In lines 18-21 a Channel Exit is specified. This exit is show in the following example. 


Listing 21.3: MQ Java Channel Exit 


1 import com.ibm.mq. 

2 import java.nio. 

3 

4 class TimeoutChannelExit implements WMQSendExit, WMQReceiveExit, WMQSecurityExit 


properties 


tTask = WatchdogTimer 
t = java.util.Timer 

10 timeout = long 

u initialized = boolean 


13 «method TimeoutChanneLlExit() 

4 say "TimeoutChannelExit Constructor Called" 
15 t = java.util.Timer() 

16 timeout = long 15000 


is method channelReceiveExit(channelExitParms=MQCXP, - 


19 channelDefinition=MQCcD, - 

20 agentBuffer=ByteBuffer) returns ByteBuffer 

21 do 

2 this.tTask.cancel() -- cancel the timer task whenever a message is read 


23 catch NullPointerException -- but catch the null pointer the first time 
24 end 

25 this.tTask = WatchdogTimer () 

26 this.t.schedule(this.tTask, this.timeout) 

27 return agentBuffer 


2 +=method channelSecurityExit(channelExitParms=MQCXP, - 


30 channelDefinition=MQCD, - 
31 agentBuffer=ByteBuffer) returns ByteBuffer 
32 return agentBuffer 
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method channelSendExit (channelLExitParms=MQCXP, — 
channelDefinition=MQCD, - 
agentBuffer=ByteBuffer) returns ByteBuffer 
return agentBuffer 


Listing 21.4: WatchdogTimer 


class WatchdogTimer extends TimerTask 


method WatchdogTimer () 
method run() 
say 'WATCHDOG TIMER TIMEOUT: HPOpenView Alert Issued' Date() 


MQ Series has traditional channel exits (programs that can look at the message contents 
before the application gets to it). In the MQI Java environment there is something akin 
to this functionality, but a Java channel exit for MQ Series has to be defined in the ap- 
plication, as shown in the previous example. The function of this particular exit is to 
implement a Watchdog timer - on a separate thread, as shown in the sample that follows 
the sample channel exit. The timer threatens here to have issues a HP OpenView alert, 
but that part has been left out. 


This particular sample has been designed to do something that is normally a bit harder 
to do: signal the operations department when something does NOT happen - here the 
assumption is that there is a payment going over the queue at least once every 20 minutes 
- when that does not happen, an alert is issued. With every message that goes through, 
the timer thread is reset, and only when it is allowed to time out, action is undertaken. 


Listing 21.5: Publish/Subscribe 


import com.ibm.mq. 
class MQPubSubSample 


properties inheritable 
queueManagerName = String 
syncPoint = Object() 
props = Hashtable 
topicString = String 
topicObject String 
subscribers = Thread[] 
subscriberCount = int 


properties volatile inheritable 
readySubscribers = int 0 --must be defined volatile 


method MQPubSubSample() 

topicString = null 

topicObject = System. getProperty("com.ibm.mq.pubSubSample.topicObject", " 
TESTTOPIC") 

queueManagerName = System. getProperty ("'com.ibm.mq.pubSubSample.queueManagerName" ,"' 
rjtestqm") 

subscriberCount = Integer.getInteger ("com.ibm.mq.pubSubSample.subscriberCount", 
100) .intValue() 

this.props = Hashtable() 

this.props.put("hostname", "127.0.0.1") 

this.props.put("port", Integer (1414) ) 

this.props.put("channel", "SYSTEM.DEF.SVRCONN") 


method main(agr=String[]) static binary 
sample = MQPubSubSample() 
sample. LaunchSubscribers() 
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x wait until all the subscriber threads have finished the subscription 
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do protect sample.syncPoint 
loop while sample.readySubscribers < sample.subscriberCount 
do 
sample.syncPoint.wait() 
catch InterruptedException 


end 
end -- loop while sample 
end -- do 


samp le.doPublish() 


method LaunchSubscribers() 
say "Launching the subscribers" 
subscribers = Thread[subscriberCount ] 


threadNo = int 0 

loop while threadNo < this.subscribers. length 
this.subscribers[threadNo] = MQPubSubSample. Subscriber ("Subscriber" threadNo) 
this.subscribers[threadNo].start() 
threadNo = threadNo + 1 

end 


method doPublish() signals IOException 

say "method doPublish started" 

destinationType = int CMQC.MQOT_TOPIC 

do 
queueManager = MQQueueManager (this.queueManagerName, this.props) 
messageForPut = MQMessage() 
say "4 y4Publishing seshigs 
messageForPut.writeString("Hello world!") 
queueManager.put(destinationType, topicObject, messageForPut) 

catch e=MQException 
say "Exception while publishing " e 

end 


class MQPubSubSample.Subscriber binary dependent extends Thread 


properties private 

myName = String 

openOptionsForGet = int CMQC.MQSO_CREATE | CMQC.MQSO_FAIL_IF_QUIESCING | CMQC. 
MQSO_MANAGED | CMQC.MQSO_NON_DURABLE 


method Subscriber (subscriberName=String) 
super (subscriberName) 
myName = subscriberName 


method run() 
do 
say myName " - 44 4Subscribingy,," 
queueManager = MQQueueManager (parent.queueManagerName, parent.props) 
destinationForGet = queueManager.accessTopic(parent.topicString, parent. 
topicObject, CMQC.MQTOPIC_OPEN_AS_SUBSCRIPTION, openOptionsForGet) 


do protect parent.syncpoint 
parent.readySubscribers = parent.readySubscribers + 1 
parent.syncPoint.notify() 

end 


mgmo = MQGetMessageOptions() 
mgmo.options = CMQC.MQGMO_WAIT 
mgmo.waitInterval = 30000 

say myName " - 4x yRetrievingyyy," 
messageForGet = MQMessage() 


do protect getClass() 
destinationForGet.get(messageForGet, mgmo) 
end 


messageDataFromGet = String messageForGet.readLine() 
say myName " - Got [" messageDataFromGet "|" 


catch e=Exception 
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say myName '"'' ""e 
e.printStackTrace() 
end 
parent.readySubscribers = parent.readySubscribers - 1 


This sample shows the publish-subscribe interfaces that at some time have been added 
to the product. This specific sample shows some Java thread complexity but is a good 
example of doing publish/subscribe work in a multithreaded way, which is a natural fit 
for this type of work. 
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MQTT 


22.1 Pub/Sub with MQ Telemetry 


Publish/subscribe (pub/sub) is a model that lends itself very well to a number of one 
publisher, many subscriber type of applications; the tools to enter this technology have 
never been as available as they are now. Also, MQTT is a small protocol that needs to be 
taken seriously: Facebook has recently become one of the largest users. 


Designed as a low-overhead on-the-wire protocol for brokers in the Internet-of-things 
age, MQTT is an exciting new development in the Messaging and Queueing realm. It is 
a good choice for any broker functionality, as the minimal message overhead is 2 bytes, 
but the maximum messages size, in one of the more popular open source brokers is a 
good 250MB, which give you a message size that is a lot higher than anything possible 
in the early years of MQ Series back in the nineties. It is now possible to do development 
with an entry level, entirely open source suite, and scale up to commercial, clustered and 
highly available implementations when needed, since the protocol has is supported by 
the base IBM WebSphere MQ product and is an added deliverable in WSMQ 7.5, after 
being available as an installable add-on for several years. 


Here I will show how extremely straightforward it is to create a pub/sub application 
using this technology. These examples use NetRexx, the Eclipse PAHO Java client library 
and the open source Mosquitto broker; all these components are completely free and 
open source. I have installed Mosquitto on my MacBook using the brew system(fn), 
which makes it as much trouble as “sudo brew install mosquitto”. NetRexx is an excellent 
language for these examples, as it is compact and avoids the C-inspired ceremony of Java 
language syntax; if your project requires Java, you can just save the generated Java source 
(using the new -keepasjava option). 

Mosquitto(fn) is written by Roger Light as an open source equivalent of IBM’s rsmb (real 
small message broker) example application, which is free but lacks source code. It is a 
small broker application that nevertheless runs production sized workloads. As MQTT, 
as opposed to the MQI or JMS API's you use when developing a messaging application, 
is an on-the-wire protocol (commercial messaging systems tend to have their own, un- 
published, on-the-wire protocols), we need an API to use it. This API consists of a set 
of calls that do the formatting of the messages to the requirements of the on-the-wire 
protocol for you. The messages themselves are just byte-arrays, which gives you the ul- 
timate freedom in designing their content. It is not unusual for connected devices to 
encode their information in a few bits; on the other hand, there is no reason not to use 
extreme verbosity in messages; as long as you send the .getBytes that your String yields, 
MQTT will send it. When encoding information in a compact way, the protocol design 
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will really pay off, because the protocol overhead, in comparison with http and other 
chatty protocols, is very low. A limited set of quality of service options (qos) will indi- 
cate if you want send and pray, acknowledged delivery or acknowledged one-time-only 
delivery. 


The API library that was chosen for these examples is that from the Eclipse PAHO 
project. This project, which is in its early stages, has C, Javascript and Java client libraries 
available. I chose the Java client because the JVM environment is where most of the or- 
ganizations that I work for will use it. The PAHO Java client library is donated by IBM 
and written by Dave Locke; it is in active development. If you want to see how the proto- 
col moves in packets over the network, I can recommend Wireshark, which does a good 
job of recognizing them (if you run on the standard port 1883) and showing you the 
message types (like ACK) and their bytes. 


After having put the NetRexx(.jar) and paho client jars on your classpath, you are good 
to go. The first example here is the publisher - this is not a fragment, but the complete 
code. For production code we might add some more checks, as enterprise environments 
always are prone to suddenly run low on disk space and suffer missing authorizations, but 
it works as it stands. Do note that you do not have to define a message topic in advance - 
just think of one any use it, at least if you are in your own environment. With Mosquitto, 
there wasn't anything to define in advance, and the running Publisher (happily lifted 
from the Java example) in NetRexx was actually the first time I talked to Mosquitto on 
my MacBook. 


Listing 22.1: MQTT Publish Sample 


import java.sql.Timestamp 
import org.eclipse.paho.client.mqttv3. 


class Publish implements MqttCallback 


method Publish() 
conOpt = MqttConnectOptions() 
conOpt.setCleanSession(@) 
tmpDir = System.getProperty("java.io.tmpdir") 
dataStore = MqttDefaultFilePersistence(tmpDir) 
clientId = MqttClient.generateClientId() 


topicName = "/world" 
payload = "hello".toString() .getBytes() 
qos = 2 
do 
broker = "localhost" 


port = "1883" 
brokerUrl = "tcp://"broker":"port 
client = MqttClient(brokerUrl,clientId, dataStore) 
client.setCallback(this) 
catch e=mqttException 
say e.getMessage() 
e.printStackTrace() 
end -- do 


client.connect() 
log("Connected to "brokerUrl" with client ID "client.getClientId()) 


-- Get an instance of the topic 
topic = client.getTopic(topicName) 


message = MqttMessage (payload) 
message.setQos (qos) 


-- Publish the message 
time = Timestamp(System.currentTimeMillis()).toString() 
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log('Publishing at: 'time' to topic "'topicName'" with qos 'qos) 
token = topic.publish(message) 


-- Wait until the message has been delivered to the server 
token.waitForCompletion() 


-- Disconnect the client 
client.disconnect() 
log("Disconnected") 


method log(line) 
say line 


method messageArrived(t=String,m=MqttMessage) 
log("Message Arrived: " t m) 


method deliveryComplete (t=IMqttDeliveryToken) 
log("Delivery Complete: " t) 


method connectionLost(t=Throwable) 
log("Connection Lost:" t.getMessage() ) 


method main(args=String[]) static 
Publish() 


Topics can have a hierarchical organization; this structure is put in by composing trees 
of topics, which are strings separated by ‘/. In this way, it is easy to compose a /news/eco- 
nomics/today topic string that gives some structure to the publication. ‘The classification 
is entirely up to the designer. 


Messaging in its original form is an asynchronous technology, and for this reason the API 
offers a callback option, where the callback receives the results of your publish action in 
an asynchronous way. ‘The broker assigns a message id which you receive back. 


The second source fragment (and again, it is no fragment but the entire application pro- 
gram) shows the subscriber. 


Listing 22.2: MQTT Subscribe Sample 


import java.sql.Timestamp 
import org.eclipse.paho.client.mqttv3. 


class Subscribe implements MqttCallback 


properties private 

client = MqttClient 

conOpt MqttConnectOptions() 

tmpDir System. getProperty("java.io.tmpdir") 
clientId = MqttClient.generateClientId() 
topicName = "/world" 

qos = 2 


method Subscribe() 
do 
connectAndSubscribe() 
catch mqx=MqttException 
log(mqx.getMessage() ) 
end 
-- Block until Enter is pressed 
log("Press <Enter> to exit"); 
do 
System.in.read() 
catch IOException 
end 


-- Disconnect the client 


client.disconnect() 
log("Disconnected") 
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method connectAndSubscribe() signals MqttSecurityException,MqttException 
conOpt.setCleanSession(1) 
dataStore = MqttDefaultFilePersistence(tmpDir) 


do 
broker = "Localhost" 
port = "1883" 
brokerUrl = "tcp://"broker":"port 


client = MqttClient(brokerUrl,clientId, dataStore) 
client.setCallback(this) 
catch e=mqttException 
say e.getMessage() 
e.printStackTrace() 
end -- do 


this.client.connect() 
log("Connected to "brokerUrl" with client ID "client.getClientId() ) 


-- Subscribe to the topic 
log('Subscribing to topic "'topicName'" qos 'qos) 
this.client.subscribe(topicName, qos) 


method log(line) 
say line 


method messageArrived(t=String,m=MqttMessage) 
log('"Message Arrived: " t m) 


method deliveryComplete(t=IMqttDeliveryToken) 
log("Delivery Complete: " t) 


method connectionLost(t=Throwable) 
do 
connectAndSubscribe() 
catch mqx=MqttException 
log (mqx. getMessage()) 
end 


method main(args=String[]) static 
Subscribe() 


In the home setup, there is a Raspberry PI running the client while a server in the at- 
tic runs the Mosquitto broker. On the Raspberry, which runs Debian wheezy with the 
soft-float ABI that, at the moment of writin, is still necessary for the Oracle ARM Java 
implementation; everything done in NetRexx runs unchanged; I just move the classes to 
it using scp. The broker on the laptop takes care of the scenario in which I suddenly can 
do some development while not connected to the net, like when I have some moments 
to reflect on the code in the IKEA restaurant while my spouse runs the serious shopping 
business. 


Security is outside of the scope of this introduction which shows you the sourcecode 
of a simple pub/sub application, but in Mosquitto the traffic can be secured using SSL 
certificates and userid/password combinations; also, the access to topics can be limited. 
In terms of availability, the Mosquitto configuration file offers an opportunity to send all 
messages for a defined set of topics to another connected broker, which might be in a 
different part of the world, or your home, to enable a redundant setup. While the broker 
does not offer the queue - transmission queue - channel setup with retrying channels 
that MQ does, the client API has some facilities to locally save the messages and retry if 
the communication was lost. Also, the last-will-and-testament facility is something that 
traditional MQ does not have. 
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Component Based Programming: Beans 


JavaBeans is the name for the Java component model. It consists of two conventions, 
for the naming of getter and setter methods for properties, and the event mechanism 
for sending and receiving events. NetRExx adds support for the automatic generation 
of getter and setter methods, throught the properties indirect option on the properties 
statement. 
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Using the NetRexxA API 


As described elsewhere, the simplest way to use the NetRexx interpreter is to use the 
command interface (NetRexxC) with the -exec or -arg flags. There is a also a more di- 
rect way to use the interpreter when calling it from another NetRexx (or Java) program, 
as described here. This way is called the NetRexxA Application Programming Interface 
(API). 

The NetRexxA class is in the same package as the translator (that is, org. netrexx.process), 
and comprises a constructor and two methods. To interpret a NetRexx program (or, in 
general, call arbitrary methods on interpreted classes), the following steps are necessary: 


1. Construct the interpreter object by invoking the constructor NetRexxA(). At this 
point, the environment’s classpath is inspected and known compiled packages and 
extensions are identified. 

2. Decide on the program(s) which are to be interpreted, and invoke the NetRexxA 
parse method to parse the programs. ‘This parsing carries out syntax and other static 
checks on the programs specified, and prepares them for interpretation. A stub 
class is created and loaded for each class parsed, which allows access to the classes 
through the JVM reflection mechanisms. 

3. At this point, the classes in the programs are ready for use. To invoke a method 
on one, or construct an instance of a class, or array, etc., the Java reflection API (in 
java.lang and java.lang.reflect) is used in the usual way, working on the Class objects 
created by the interpreter. To locate these Class objects, the API’s getClassObject 
method must be used. 


Once step 2 has been completed, any combination or repetition of using the classes is 
allowed. At any time (provided that all methods invoked in step 3 have returned) a new 
or edited set of source files can be parsed as described in step 2, and after that, the new 
set of class objects can be located and used. Note that operation is undefined if any at- 
tempt is made to use a class object that was located before the most recent call to the 
parse method. 

Here's a simple example, a program that invokes the main method of the hello.nrx pro- 
grams class: 


Listing 24.1: Try the NetRexxA interface 


options binary 
import org.netrexx.process.NetRexxA 


interpreter=NetRexxA() -- make interpreter 
files=['hello.nrx'] -- a file to interpret 


flags=['nocrossref', 'verbose0'] -- flags, for example 
interpreter.parse(files, flags) -- parse the file(s), using the flags 
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helloClass=interpreter.getClassObject(null, 'hello') -- find the hello Class 


-- find the 'main' method; it takes an array of Strings as its argument 
classes=[interpreter.getClassObject('java.lang', 'String', 1)] 
mainMethod=helloClass.getMethod('main', classes) 


-- now invoke it, with a null instance (it is static) and an empty String array 
values=[Object String[0] ] 


loop for 10 == Let's call it ten times, for fun... 
mainMethod.invoke(null, values) 
end 


Compiling and running (or interpreting!) this example program will illustrate some im- 
portant points, especially if a trace all instruction is added near the top. First, the perfor- 
mance of the interpreter (or indeed the compiler) is dominated by JVM and other start- 
up costs; constructing the interpreter is expensive as the classpath has to be searched 
for duplicate classes, etc. Similarly, the first call to the parse method is slow because of 
the time taken to load, verify, and JIT-compile the classes that comprise the interpreter. 
After that point, however, only newly-referenced classes require loading, and execution 
will be very much faster. 

The remainder of this section describes the constructor and the two methods of the Net- 
RexxA class in more detail. 


24.1 The NetRexxA constructor 


Listing 24.2: Constructor 


NetRexxA() 


This constructor takes no arguments and builds an interpeter object. This process in- 
cludes checking the classpath and other libraries known to the JVM and identifying 
classes and packages which are available. 


24.2 ‘The parse method 


Listing 24.3: parse 


parse(files=String[], flags=String[]) returns boolean 


The parse method takes two arrays of Strings. The first array contains a list of one or 
more file specifications, one in each element of the array; these specify the files that are 
to be parsed and made ready for interpretation. 

The second array is a list of zero or more option words; these may be any option words 
understood by the interpreter (but excluding those known only to the NetRexxC com- 
mand interface, such as time). The parse method prefixes the nojava flag automatically, 
to prevent .java files being created inadvertently. In the example, nocrossref is supplied 
to stop a cross-reference file being written, and verbose0 is added to prevent the logo and 
other progress displays appearing. 

The parse method returns a boolean value; this will be 1 (true) if the parsing completed 
without errors, or 0 (false) otherwise. Normally a program using the API should test this 





13Note that the option words are not prefixed with a -. 
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result an take appropriate action; it will not be possible to interpret a program or class 
whose parsing failed with an error. 


24.3 The getClassObject method 


Listing 24.4: getClassObject 


getClassObject(package=String, name=String [,dimension=int]) returns Class 


This method lets you obtain a Class object (an object of type java.lang.Class) represent- 
ing a class (or array) known to the interpreter, including those newly parsed by a parse 
instruction. 

The first argument, package, specifies the package name (for example, com.ibm.math). 
For a class which is not in a package, null should be used (not the empty string, ”). 

The second argument, name, specifies the class name (for example, BigDecimal). For a 
minor (inner) class, this may have more than one part, separated by dots. 

The third, optional, argument, specifies the number of dimensions of the requested class 
object. If greater than zero, the returned class object will describe an array with the spec- 
ified number of dimensions. This argument defaults to the value 0. 

An example of using the dimension argument is shown above where the java.lang.String[] 
array Class object is requested. 

Once a Class object has been retrieved from the interpreter it may be used with the Java 
reflection API as usual. The Class objects returned are only valid until the parse method 
is next invoked. 


24.4 ‘The exiting method 


Syntax: 


Listing 24.5: exiting 


exiting() returns boolean 


If this method returns true, an interpreted program has invoked the NetRexx “exit” in- 
struction to shut down the interpreter. If more programs need to be interpreted, a new 
instance of the interpreter will need to be created with the NetRexxA() constructor. 


24.5 Interpreting programs contained in memory strings 


Programs can be interpreted directly from memory strings. The first extension adds an 
optional array of strings containing programs to the standard parse API. It is mainly 
useful to IDE developers. It also serves as the basis to support two other extensions doc- 
umented below. 


Listing 24.6: parse program in memory buffer 


method parse(filestrings=String[], programstrings=String[], flagstrings=String[], 
logfile=PrintWriter null, outfile=PrintStream System.out) returns boolean 


Parses a set of files, under specified flags: 


filestrings is a list of program names, 

programstrings is a list of program strings, 

flagstrings is a list of flags, 

logfile is a PrintWriter for parse output messages (optional), 
outfile is a PrintStream for console output messages (optional), 


This method returns 1 if no error 


The 


second extension is a new easy to use method to parse and interpret a program 


contained in a string. 


Listing 24.7: parse program in string 


1 method interpret(programname=String, programstring=String, argstring=String "", 


flagstring=String '"", logfile=PrintWriter null, outfile=PrintStream System.out) 
returns boolean 


A convenience method to interpret a single NetRexx program in a string: 


programname is the program name, 

programstring is the program string, 

argstring is the argument string (optional), 

flagstring is the translator flags string (optional), 

logfile is a PrintWriter for parse output messages (optional), 
outfile is a PrintStream for console output messages (optional), 


This method returns 1 if no parse error. The default flag is -verbose0 


Here is a simple example using the interpret method: 


Listing 24.8: interpret from string 


1 import org.netrexx.process. 

2 netrexxapi=NetRexxA() 

3 myprog="Say ‘argument string is' arg" 

4 netrexxapi.interpret("myprog",myprog,"a passed argument") 


The 


third extension is a slightly more complex “eval” method that allows a program to 


call a static method in a program string and receive an object back. 


Listing 24.9: eval 


1 method eval(programname=String, programstring=String, methodname=String, argstring= 


String "", flagstring=String "", logfile=PrintWriter null, outfile=PrintStream 
System.out) returns Object 


A convenience method to interpret a method from a NetRexx program in a string and 
return an object: 


programname is the program name, 

programstring is the program string, 

methodname is the method name to call - the method must accept a String array 
like main methods, 

argstring is the argument string (optional), 

flagstring is the translator flags string (optional), 





14Note that program strings which are not named in the name list are ignored. 
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¢ logfile is a PrintWriter for parse output messages (optional), 
* outfile is a PrintStream for console output messages (optional), 
This method returns an object if no error. The default flag is -verbose0 


Here is a simple example using the eval method: 


Listing 24.10: eval example 


import org.netrexx.process. 

netrexxapi=NetRexxA() 

termpgmstring='method term(sa=String[]) static returns rexx;i=Rexx(sa);return 1/7' 
say netrexxapi.eval("termpgm", termpgmstring, "term" ,99) 
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Interfacing to Scripting Languages 


NetRexx contains standardized Java Scripting support, and the NetRexxC jar file is a 
self-contained JSR223 scripting engine. This facility opens up a number of possibili- 
ties to interface in a standardized manner with several scripting languages and other 
infrastructure, and offers an easy way for including interpreted NetRExx code in JVM 


applications. JSR223 is a standard for interacting with scripting languages that consists 
of: 


. A mechanism to find out for which scripting languages support is available 
. A way to choose one of them 
. An eval() call to dynamically specify and execute a program 


Be WO bh 


. A bindings mechanism to bind variable names to values, to exchange objects with 
scripts 

. Optionally, a way to execute methods, functions or routines from larger programs 

6. Optionally, a way to keep already compiled scripts around for repeated execution 

(with associated higher performance) 


on 


The JSR223 specification details the calls that are available in the javax.scripting 
package. To use the JSR223 interface, Java 6 or higher is required. The JAR file specifica- 
tion defines a service as a well-known set of interfaces and (usually) abstract classes. A 
service provider is a specific implementation of such a service. For scripting, the service 
consists of javax.script.ScriptEngineFactory. All classes that implement this inter- 
face are service providers. Service providers identify themselves by placing a so-called 
provider-configuration file in META-INF/services. Its filename corresponds to the fully 
qualified name of the service class, which is javax.script.ScriptEngineFactory. Each 
line of this file contains the fully qualified name of a service provider. The factory class of 
the NetRExx connector is org.netrexx.jsr223.NetRexxScriptEngineFactory. So the 
file META-INF/services/javax.script.ScriptEngineFactory contains one line with 
exactly this class name. 


25.1 Which JSR223 engines are on my system? 


The number of JSR223 engines available varies per JVM implementation. The following 
code can be used to list these. 


Listing 25.1: Enumerate the JSR223 Engines on a JVM 





1 import javax.script.ScriptEngine 
2 import javax.script.ScriptEngineFactory 





15 ttp://ww.jcp.org/en/jsr/detail?id=223 
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import javax.script.ScriptEngineManager 


method main(args=String[]) static 

manager = ScriptEngineManager () 

factories = manager.getEngineFactories() 

it=factories.iterator() 

loop while it.hasNext() 
factory=ScriptEngineFactory it.next() 
f=ScriptEngine factory.getScriptEngine() 
say "className = " f.getClass.getName 
engineName = factory.getEngineName() 
engineVersion = factory.getEngineVersion() 
langName = factory.getLanguageName() 
langVersion = factory.getLanguageVersion() 
say "engineName = " engineName engineVersion langName langVersion 
say 

end 


For example, the Java 8 SE version by Oracle on macOS delivers out of the box: 


I 


className org.netrexx.jsr223.NetRexxScriptEngine 


engineName = NetRexx Script Engine V1.0.0 NetRexx 3.07 


| 


I 


className jdk.nashorn.api.scripting.NashornScriptEngine 
engineName = Oracle Nashorn 1.8.0_144 ECMAScript ECMA - 262 Edition 5.1 


| 


As one can see, the name of the engine, the language and its release are standard features 
for this query. The NetRexxC jar file on the classpath adds the NetRExx implementation. 
There can be any number of additional jar archives on the classpath to deliver engines 
for different JSR223 implementations for different languages. 


25.2 Selecting an engine 


When developing a program one is probably interested in using a specific implementa- 
tion, and it is possible to request the loading of a specific JSR223 engine by name. 


Listing 25.2: Choosing an engine 


import javax.script. 


Manager = ScriptEngineManager () 
nrEngine = manager. getEngineByName("NetRexx") 


The language engine can be selected by its short name, so there is no need to specify the 
longer name or its version. 


25.3 Evaluating a script 


This example shows how to do a simple thing that illustrates the value of being able to 
do this from other environments: calculating some number with numeric precision set 
to some value that other languages cannot handle. 


Listing 25.3: Evaluating a script 


/x Simple script invocation ,/ 
nrEngine.eval('numeric digits 17; say 111111111 , 111111111') 


92 


- 


iS) 


w 


The output from this script would be: 


12345678987654321 


25.4 Bindings 


Bindings are name-value pairs whose keys are strings - they can be of RExx type. Their 
behavior is defined through the javax.script.Bindings interface. As for ScriptContext, 
a basic implementation is provided called SimpleBindings. Although bindings be- 
long to script contexts, ScriptEngine provides createBindings(), which returns an 
uninitialized binding. Another method, getBindings(), exists to return the bindings 
of a certain scope. There are at least two scopes, ScriptContext.GLOBAL_SCOPE and 
ScriptContext.ENGINE_SCOPE. They represent key-value pairs that are either visible to 
all instances of a script engine that have been created by the same Scr iptengineManager, 
or visible only during the lifetime of a certain script engine instance. The following pro- 
gram illustrates the use of bindings to store a value, 42, into the binding called answer 
and then using its retrieved value in the evaluation of the statement ’say “the answer 
is” answer ’. The next action uses the handle one for a value of 1, and uses its retrieved 
value to add it to the value previously contained in the binding answer. 


Listing 25.4: Object Bindings 


import javax.script. 
nrEngine = ScriptEngineManager () .getEngineByName("'NetRexx"') 


/x% Simple script invocation ,;/ 
nrEngine.eval('numeric digits 17; say 111111111 , 111111111') 


/x script invocation with bindings ,/ 

answer = 42 

nrEngine.put("answer", answer) 
nrEngine.eval('say ''the answer is ''answer') 


one = 1 
nrEngine. put ("onemore",one) 
nrEngine.eval('say ''one more is ''answer+onemore') 


Note that in line two, the invocation is shortened a bit by getting rid of the intermediate 
manager object for instantiation of the language interface. Also note that in line 10, we 
chose, for illustration purposes, to store the one object into the bindings structure using 
a different name, onemore. This shows that the string used as identifier for the object is 
just a handle to it, and nothing more. This would yield: 


12345678987654321 
the answer is 42 
one more is 43 


The different possibilities and language combinations will be discussed in the paragraphs 
below. 
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25.4.1 Obtaining a returncode 


The variable binding used for the return code from the NetRexx program is called 
returnobject. This program illustrates its use: 


Listing 25.5: Obtaining a returncode 


import javax.script. 
nrEngine = ScriptEngineManager () .getEngineByName("'NetRexx"') 
/x check returncode ,/ 


say nrEngine.eval('NetRexxScriptEngine. instance. put("returnobject", "99")') 


99 


25.5 Interpreted execution of NetRExx scripts from jrunscript 


Another way of calling any NetRexx program, for interpretation, is to use the standard 
jrunscript executable that is included in Java 1.6 and beyond. For example, in the exam- 
ples/rosettacode directory, one could specify: 


jrunscript -l netrexx -cp $CLASSPATH -f RCSortingHeapsort.nrx 


The -l option instructs the jrunscript handler to choose NetRexx as its standard scripting 
language. For NetRexx to be eligible as a scripting language, NetRexxC.jar must be on the 
jrunscript classpath, which is a separate classpath from the standard one. In this setup, 
even NetRExx programs with a filename that is not valid as a classname, can be executed 
as an interpreted script. 


25.6 Using JavaScript from NetREXx programs 


JavaScript support is built in from Java 1.6 onwards, and using it does not require placing 
another library on the classpath. Using JavaScript from NetREexx can have benefits, for 
example when using types native to JavaScript, like the JSON data interchange format. 


Listing 25.6: Run JavaScript 


import javax.script. 
jsEngine = ScriptEngineManager () .getEngineByName ("JavaScript") 


jsEngine.eval('var foo = {};') 


jsEngine.eval('foo. foundation = "RexxLA";') 
jsEngine.eval('foo.model = "open";') 
jsEngine.eval('foo.week = 42;') 
jsEngine.eval('foo.transport = "car";') 


jsEngine.eval('foo.month = 7;') 
jsEngine.eval('bar = JSON.stringify(foo) ;') 


jsonString = jsEngine.get('bar') 
say jsonString 


which yields the following result: 
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{” foundation”: ”RexxLA”, *model”: ”open”, *week”:42, ”transport”:”car”, ”*month 
er Ae 


25.7 Using AppleScript on macOS 


On macOS you can run an AppleScript using NetRExx. 


Listing 25.7: Run AppleScript 


import javax.script. 
-- does not work in recents macos versions 


/x 
Instead of ScriptEngine engine = mgr.getEngineByName("AppleScript"); you must use: 


ScriptEngine engine = mgr.getEngineByName("AppleScriptEngine") ; 


In your src directory create directory META-INF 

In your src directory create directory META-INF/services 
Create file META-INF/services/javax.script.ScriptEngineFactory 
In this file is one line: 
apple.applescript.AppleScriptEngineFactory 

«/ 


appleEngine = ScriptEngineManager ().getEngineByName ("AppleScriptEngine") 
context = appleEngine. getContext() 

bindings = context. getBindings (ScriptContext.ENGINE_SCOPE) 

bindings. put("javax_script_function", "getName") 
bindings.put(ScriptEngine.ARGV, 'Stranger') 


appleScript = 'on getName(default_) \n'- 
‘tell application "Finder" \n'- 
‘display dialog "What is your name?" default answer default_ with icon note \n' 


"set myName to the text returned of the result \n'- 

"delay 0.5 \n'- 

‘display dialog "Hi there, " & myName & "! Welcome to AppleScript!" with icon 
note \n'- 

‘end tell\n'- 

"return myName\n'- 
‘end getName' 


result = appleEngine.eval(appleScript, context) 
say result 


The AppleScript interpreter expects end-of-line characters at the end of every line, so 
make sure to include them in your script. The above script shows it is fairly straightfor- 
ward to put a dialog box with a question on the screen. The example shows how to give 
an argument (ARGV) to a method, and how to put the method name in the bindings 
object in order to return the result upon evaluation. 


25.8 Execution of NetREXxx scripts from ANT tasks 


The jsr223 engine enables us to execute NetRexx scripts from the ant“4 building tool 
using the <script> tag. This was already possible using the BSF library, where NetREXx 
was one of the originally supported languages, but has become more straightforward 
with jsr223 scripting. 


l6http ://ant.apache.org 
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Listing 25.8: Run a NetRExx script in Ant 


1 <project name="MyProject" basedir=""."> 
<description> 

demonstration of ant jsr223 netrexx scripting 
</description> 


<property name="divider" value="81" /> 

<script Llanguage="netrexx" manager="javax'"'> 
say "100/"divider '= ' 100/divider 

9 </script> 

10 </project> 


2 
3 
4 
5 
6 
7 
8 


Note that properties can be set in other parts of the ant xml file and used in the ant script. 
This script yields the following output: 


1 Buildfile: /Users/rvjansen/apps/netrexx-code/documentatton/pg/antscript. 
xml 

2 [script] 100/81 = 1.2345679 

3 

4 BUILD SUCCESSFUL 

s Total time: 0 seconds 


The task may use the BSF scripting manager or the JSR 223 manager that is included 
in JDK6 and higher. This is controlled by the manager attribute. The JSR 223 scripting 
manager is indicated by ”javax’, as shown on line 7. 


All items (tasks, targets, etc) of the running project are accessible from the script, using 
either their name or id attributes (as long as their names are considered valid Java identi- 
fiers, that is). This is controlled by the ’setbeans” attribute of the task. The name ’project” 
is a pre-defined reference to the Project, which can be used instead of the project name. 
The name “self” is a pre-defined reference to the actual <script>-Task instance. From 
these objects you have access to the Ant Java API. 


A classpath for execution of the script can be set using the classpath attribute. A script 
contained in a separate file can be executed using the src attribute. 


25.9 Integration of NetRexx scripting in applications 


Several applications offer a facility to script functionality using the javax.scripting inter- 
face, akin to the way applications use the RexxSAA interface for this purpose. 


25.10 Interfacing between ooRexx and NetRExx using BSF4ooRexx 


BSF is a system for language interaction that originated in a research project at IBM, 
and predates JSR223 (and certainly its implementation in Java 6) for a number of years. 
BSF 2.x has its own interface, while modern BSF versions are an implementation of the 
JSR223 interfaces. BSF40oRexx enables a bidirectional interface between ooRexx and 
Java, and enables one to use the large class library support for Java in ooRexx programs, 
but likewise the execution of ooRexx code from Java (including NetRExx) programs. 
BSF4ooRexx contains some special support for JVM programs written in NetRExx. 
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25.11 General jsr-223 Implementation Notes 


This section describes some notes pertaining to specific jsr223 for NetRExx design and 
implementation decisions. 


« All engine scope bindings are passed to the script as variables - note that bind- 
ing names containing periods have the periods changed to underscores to be legal 
variable names. 

« The NetRexx script engine is reused unless the script returned via an “exit” state- 
ment and the bindings are persistent which means that scripts will see the bindings 
(Objects) created by previous scripts 

¢ Arguments are passed both as the normal arg string and as the array binding 
javax.script.argv i.e. script variable javax_script_argv. 

* Scripts are executed via the NetRexxA API for interpreting a program from a string 
so they are not written to files. 

¢ The current version of the engine has no other optimization and only support for 
bare minimum JSR223 features (No compilable, invokeable, preparse or caching or 
user profiles or console, etc.). 

¢ When running as an Ant Script task, properties whose names contain periods are 
not passed to the bindings and must be accessed via project.getProperty(’some.name’) 
The workaround is to define a local Ant property as a global first and the scriptengine 
will overlay the global value with the local value in the bindings map 

¢ When runningas an Ant Script task, properties can be set via project.setProperty(’some.name, 
’some value’) 

¢ Script parms can be passed in an “arg” binding. Parse flags can be passed with a 

*netrexxflags” binding or in Ant with the usual ”ant.netrexx.verbose’, etc properties. 

Ant scripts can use the nested classpath facility - It is automatically added to the 

classpath that NetRexx scans. Likewise any path segments from a thread context 

URLclassloader are added. 

¢ The engine will run programs (ie that have a main class) as well as scripts but bind- 
ings cannot then be auto added to the program namespace so programs have to 
load bindings like this: NetRexxScriptEngine. getObject (”objectname”) 
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26 





NetRExx Tools 


26.1 Editor support 


This chapter lists editors that have plugin support for NetRExx, ranging from syntax 
coloring to full IDE support (specified), and Rexx friendly editors, that are extensible 
using RExx as a macro language (which can be the first step to provide NetRExx editing 
support). 


26.1.1 JVM - All Platforms 


JEdit Full support for NetRExx source code editing, to be found at 


//www.jedit.org. 





NetRexxDE A revisions with additions of the NetRexx plugin for jEdit, moving to 
a full IDE for NetRExx. http: //kenai.com/projects/netrexx-misc 


Eclipse Eclipse has a NetRexx plugin that provides a complete IDE envi- 
ronment for the development of NetRExx programs (in alpha re- 
lease) by Bill Fenlason. The project is situated at SourceForge (http: 
//eclipsenetrexx.sourceforge.net/)). Chapter 27] on page [103] dis- 
cusses the setup of Eclipse to build the translator itself; and has instruc- 
tions for the setup of the NetRExx plugin. 





26.1.2 Linux 


Emacs _netrexx-mode.el (in the NetRExx package in the tools directory) runs on 
GNU Emacs, which is installed by default on most Linux developer distri- 
butions. 





vim vi with extensions 


26.1.3 MS Windows 


Emacs netrexx-mode.el (in the NetRExx package in the tools directory) runs 


on GNU Emacs for Windows. http://www. gnu.org/software/emacs/ 
indows/faq.html 


vim vi with extensions 
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26.1.4 macOS 


Aquamacs_ A version of Emacs that is integrated with the macOS Aqua look and 


feel. (http: //www.aquamacs.org). NetRExx mode is included in the 


NetRexx package in the tools directory. 





Emacs netrexx-mode.el (in the NetRExx package) runs on GNU Emacs for ma- 
cOS. http://www. gnu.org/software/emacs 
Vim Vi with extensions 


26.2 Java to Nrx (java2nrx) 


When working on a piece of Java code, or an example written in the language, sometimes 
it would be good if we could see the source in NetRExx to make it more readable. This 
is exactly what java2nrx by Marc Remes does. It has a Java 1.5 parser and an Abstract 
Syntax Tree that delivers a translation to NetRexx, to the extend of what is currently 
supported under NetRexx. 


At the moment it is to be found at gitclonegit://git.code.sf.net/p/netrexx/ 
in the tools directory. 


It is started by the java2nrx. sh script; for convenience, place java2nrx.sh and java2nrx.jar 
in the same directory. NetRexxC and java must be available on the path. 


Usage: Alternatively: 
FIGURE 5: Java2nrx 1 


java2nrx 
——(Gava -jar javaanrx. jar) infile.java AG J 
out.nrx 


FIGURE 6: Java2nrx 2 





























java2nrx 


——{(javaanrx.sh/.bat) 























i filename.java -X—— 















-stdout 


-run 


options other NetRexxC options 




















-nre runs NetRexxC compiler on output nrx file 
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-stdout prints NetRexx file on stdout 
-run runs generated translated NetRexx output file 
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Using Eclipse for NetRexx Development 


This is a guide for first time Eclipse users to set up a NetRexx development project. It is 
not a beginners guide to Eclipse, but is intended to explain how to download the NetRexx 
compiler source from SVN to be able to modify and build it using Eclipse". 

It is detailed and hopefully foolproof for someone who has never used Eclipse. It assumes 
a Windows user, but if you are a Linux or Mac user, you will no doubt understand what 
to do. 

This guide is for Eclipse 4.2 (Juno), written August, 2012. New Eclipse releases occur 
every 4 months, so there may be differences depending on what the current version is. 


27.1 Downloading Eclipse 


There are many different preconfigured versions of Eclipse. As you become more expe- 
rienced with it you may wish to use a different distribution, but the one specified here 
makes some things simple. It does contain some things that you may never use. 


1. Make a new folder for the project. Name it appropriately (e.g. EclipseNetRexx) 

2. Browse to eclipse.org, and click on “Download”. 

3. Download the version named ECLIPSE IDE FOR JAVA DEVELOPERS for your 
your operating system. 

4, The download is about 150 MB. 

5. Unzip the downloaded file into your project folder. 


27.2 Setting up the workspace 


There are different strategies for managing Eclipse workspaces. Eclipse defaults to 
putting the workspace in your Windows documents folder - probably not what you 
want to do. The following is perhaps the most simple way. 


1. Open the project folder. It will now contain a folder named eclipse. 

2. Add a new folder named “workspace” in the project folder to go along with the 
eclipse folder. 

3. Open the eclipse folder, and create a shortcut to eclipse.exe. 

4. Move the shortcut to the desktop and rename it to something like “Eclipse Net- 
Rexx”. 





Tf you have questions or comments, feel free to contact Bill Fenlason at billfen@hvc.rr.com. 
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5. Close the project folder, and double click the shortcut to start Eclipse. 
6. The “Select a workspace” dialog comes up - don't use the default. 

7. Browse to the workspace folder that you just created and select it. 

8. Click (check) the “Use this as the default” box, and click OK. 


27.3 Shellshock 


If you have never used Eclipse, it can be a bit overwhelming. It is rather complicated, and 
has endless options, etc. In addition there are at least a thousand different plugins. 


You will be greeted by a Welcome screen - you may find it interesting or boring. Exit 
from it via tback to the welcome screen from: Main Menu -> Help -> Welcome. 


27.4 Installing Git 


Modern versions of Eclipse come with Git support built in. If not, install it from the 
Eclipse Marketplace. 


27.5 Downloading the NetRexx project from the SVN repository 


The Git repository on SourceForge contains the NetRexx compiler/translator, documen- 
tation, examples, etc. These instructions assume you want only the compiler project. 


1. The NetRexx Git repository clobe command is: gitclonegit://git.code.sf. 
net/p/netrexx/codenetrexx-code 


2. Copy it (for pasting) from above, or get it from the kenai or netrexx.org site. 


27.6 Setting up the builds 


Ant support is built into Eclipse, but it must be configured to be able to access the boot- 
strap NetRexx compiler. 


1. Double click on the build.xml file name in the package explorer. Note that its icon 
is an ant. 

2. The build file will open in an editor window. 

. Right click in the window to bring up a context menu, and select Run As -> 2 Ant 
Build 

. Do NOT select 1 Ant Build. 

. The Ant configuration dialog comes up - it will show you all the targets, etc. 

. Click on the Classpath tab, and then click on User Entries. 

. Now click on Add External Jars to bring up the Jar Selection dialog. 

. Navigate to the lib folder in the project folder. Make sure you are not in the build 
folder. 

9. Double click on NetRexxC jar to select it. 
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10. Click on the Refresh tab, and check the Refresh resources on completion box. 

11. Click Run to build the distribution. The messages will appear in the console listing 
below. 

12. The java doc step may fail. 

13. Close the build.xml file (X on the tab). 


You can configure the ant build by using the configuration dialog in Run As -> 2 Ant 
Build. You may want to check “compile” and “jars” to run those steps. Use Apply to save 
the configuration. 

There are two different builds. The second build.xml file is in the project -> tools -> ant- 
task folder. Open it up and repeat the above steps for that build.xml file. Each build file 
has its own ant configuration, and once set selecting Run As -> 1 Ant Build will run it. 
Or just hit F11. 


27.7 Using the NetRexx version of the NetRexx Ant task 


The above process uses the standard NetRexx Ant task, not the new one. To use the new 
one: 


1. Main Menu -> Window -> Preferences -> Ant -> Runtime. 

2. Open up and select Ant Home Entries. Then click on Add External Jars 

3. Navigate to the lib folder in the project and select ant-netrexx.jar 

4. The jar will appear at the bottom of the list. 

5. Use the UP button to move it up (ahead) of the apache ant version, click OK 


27.8 Setting up the Eclipse NetRexx Editor Plugin (Optional) 


The NetRexx Editor plugin provides syntax coloring and error checking for nrx files, as 
well as one click compiling and translating. 


. Click on Main Menu -> Help -> Eclipse MarketPlace. 

. Type NetRexx in the search box and hit enter. 

. Click the Install button next to the Eclipse NetRexx package. 

. Click Next, Accept the License, Finish, OK to unsigned content, and Yes to restart 
Eclipse. 

5. Click Main Menu -> Window -> Preferences -> NetRexx Editor to explore it 
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28 





Platform dependent issues 


28.1 Mobile Platforms 


Android” is a version of Linux and friendly to NetRExx programs. Indeed, with NetRExx 
performing so much better than the closest competition (jRuby, jython) on these devices, 
there might be a bright future for NetRExx in these environments. 


However, there are some drawbacks, caused by the security architecture put in place. 
Free, unfettered programming like one can do on a desktop machine is a rare occurrence 
on these devices, and to get programs running on them requires some knowledge of the 
security architecture that has been put in place for mobile operating systems. 


While Apple development still employs a closed model that allows programming only by 
buying a license with accompanying certificates, and vetting by the App Store employ- 
ees, and an assumption you will program in Objective-C, Android allows programming 
but not as straightforward as we know it. To make simple command-line NetRExx pro- 
grams, both device types need to be rooted to allow optimal access. Android allows the 
installation of applications without vetting by third parties, but dictates a programming 
model that incurs some overhead - which is a drawback for the occasional scripter. 


28.1.1 Android 


The security model of Android is based on least needed privilege and is implemented by 
assigning each application a different userid, so that applications on the same device (be 
it a phone or a tablet) cannot get to each others data. The consequence of this is that 
simple NetRExx programming and scripting 


28.1.2 Apple IOS 


Nonewithstanding the current intention of Apple to only allow Objective-C as a pro- 
gramming language on the iPhone and iPad, NetRexx on IOS works fine. This is what 
one should do to make it work: 


1. Jailbreak"8 the device. This is necessary until a more sensible setup is used. I used 
Spirit; it synchs the phone with the hack and then Cydia is installed, an application 
that does package management the Debian way 

2. Choose the “developer profile” on Cydia when asked. This applies a filter to the 
packages shown (or rather it doesn't) - but you need to do it in order to see the 





18Note that jailbreaking an iPhone is against Apple’s End Use License Agreement) and might be illegal in some jurisdictions. 
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prerequisites 
3. OpenTerminal will help you to do command line operations on the phone itself 
4, The prerequisites are a Java VM (JamVM installs a VM and ClassPath, the open 
Java implementation) and Jikes, the Java compiler written in C and compiled to the 
native instruction set of the phone, which is ARM - most processors implementing 
this have Jazelle, a specials instructionset to accelerate Java bytecode. However, this 
feature is seldom used. 


The phone can also be logged on to using ssh from your desktop. Do not forget to change 
the password for the ‘root’ user and the ‘mobile’ user, as instructed in the Cydia package. 
Note that this type of information will can be made inaccurate very swiftly. 


When this is done, NetRexxC.jar can be copied to the phone. I did this using ’scp Net- 
RexxC.jar mobile@10.0.0.76: (use the password you just set for this userid) (and because 
my router assigned 10.0.0.76 to the phone today). I crafted a small ‘nrc’ script that does 
a translate and then a Java compile using jikes (and I actually wrote this on the phone 
using an application called ’iEdit’ - nano, vim and other editors are also available but I 
found the keyboard scheme to type in ctrl-characters a bit tedious - you type a ball’ char- 
acter and then the desired ctrl char, while shifting the virtual keyboard through different 
modes): 


nrc: 
java -cp ~/NetRexxC.jar COM.ibm.netrexx.process.NetRexxC $x 


Now we can do a compile of the customary hello.nrx with */nrc -keep -nocompile hello’ 
(notice that this is all in the home directory of the ‘mobile’ user, just like the jar that I just 
copied. ‘The resulting hello.java.keep can then be mved to hello.java and compiled with 
jikes hello.java. This produces a class that can be run with ‘java -cp NetRexxC jar hello’ 


28.2 IBM Mainframe: Using NetRExx programs in z/OS batch 


Traditionally the mainframe was a batch oriented environment, and much of the work- 
load that counts still executes in this way. To be able to use NetRExx with Job Control 
Language (JCL) in batch address spaces, accessing traditional datasets and interacting 
with the console when needed, we need to know a bit more. This will be explained in 
these paragraphs. 


A standard component of z/OS since version 1.8 or so is jzos, which acts as glue between 
the unix-like abstractions the JVM works with and the time tested way of working on 
z/OS, with its SAM and VSAM datasets, its Partitioned Data Set (PDS) file organization, 
the ICF Catalogs and console address space; all of which in existence long before Java 
reared its head in our IT environments. 


The manuals will teach you that there are several ways to interact with HFS/OMVS re- 
sources in JCL, but the alternatives to jzos have so many drawbacks that it is the only 
sensible way to run NetRExx programs in the batch environment. 
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Building the NetRExx translator 


It is easy to build the NetRexx translator from source. Prerequisites are: 


1. A Java Virtual Machine 
2. A Git client 


NetRexx can be built on all platforms that it runs on. NetRexx has been bootstrapped 
in 1996 and subsequently has been used to compile itself. Every checkout of the source 
code contains the bootstrap’ compiler, which is the previous release version. Only the 
official release branches contain the same release of the compiler - to prove that it still 
could compile itself on release. Theoretically, it is possible to break things by introducing 
changes that make it impossible for the compiler to compile itself - it is our job that these 
changes are not released to a wider audience, but rolled back in time. In Git, that is one 
of the easiest things to do: just delete your working copy and issue a svn up command - 
and you have travelled back in time to where things still did work. 


29.1 Repository 


The NetRExx source code repository is hosted at the SourfeForge Git repository. To get 


the code on your system, you should register at the NetRexx project https: //kenai. 
and check the repository out using Git. For this version man- 


agement package are many graphical user interfaces, but what is shown here, is the com- 
mand line version. Choose a suitable place as working directory - you can later move it 
around as you please. 


git clone git://git.code.sf.net/p/netrexx/code netrexx-code 


Note: This will checkout the whole repository to your local system; including previous 
versions, experimental branches and personal sandboxes of other developers. 


In the trunk directory the most current version of the source code, including that of the 
documentation, is to be found. 


29.2 The buildfile 


The official buildfile is called build.xml and the ant utility is used for building NetRExx 
from source. ‘This file contains a number of tasks. To build the translator, make sure that 
netrexx/netrexxc/trunk is the current directory, and issue the command: 
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java -jar ant/ant-launcher.jar compile 
followed by 
java -jar ant/ant-launcher.jar jars 


This will build the compiler from source and create a build directory in the current di- 
rectory. In build/lib the NetRexxC and NetRexxR jars are put by the archiving process 
that is started by the jar task. These new jars can be used immediately, by having them 
(NetRexxC will suffice) on the classpath. 


29.3 Testing 


Currently, there are two locations that contain the tests. The first is the org. netrexx.process.diag 
package, which currently is being integrated into the trunk/test directory. This direc- 

tory contains, in addition to the traditional “diag” tests that have been modified to run 

under jUnit, some of the tests for the newer functionality. These tests are accessible using 

a make process that uses makefile as its build build file. The command 


make test 


will compile and run the tests; jUnit will report on progress and results. 
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Translator inner workings 


This chapter includes all documentation on the inner workings of the translator that is 
available. Its purpose is to assist with debugging serious problems or ease the introduc- 
tion to the toolset for programmers who want to help the open source effort forwards. 


30.1 Translator source files 


The translator source is part of the package org.netrexx.process. The runtime support, 
including the Rexx type, is in the package netrexx. lang. 


The source files in table 3 all correspond to a specific NetRexx clause, all created by Rx- 
Parser, and all implementing RxClauseParser. Each is responsible for syntax checking, 
semantic processing, and code generation for the corresponding clause. RxClass and 
RxMethod are the critical classes. RxNop is the simplest. Method-term instructions are 
currently handled in RxParser but should have a separate class in this list. 
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NetRexxC.nrx 


TABLE 2: Translator source files 


The ‘main program’ 











nrc.prp Error messages (becomes NetRexxC. properties resource bundle) 
RxArray.nrx Parsed array reference 
RxClasser.nrx The class ‘factory’; finds classes and packages, loads classes, finds fields in pack- 


ages, etc. 





RxClassImage.nrx 


Loads and parses a .class file (from zip or directory byte stream) 





RxClassInfo.nrx 


Known information about a class 





RxClassPool.nrx 


Collection of known classes (maintained by RxClasser) 





RxClause.nrx 


The tokens and object corresponding to a clause 





RxClauseParser.nrx 


Interface: all clause objects implement this 





RxClauser.nrx 


Tokenizer (lexical analysis/parse) 





RxCode.nrx 


Represents encoded piece of program (e.g., an expression or clause). Holds 
information about the source of the code, and the code itself (currently only 
Java source code). At present, RxCode is only used for terms and expressions; 
clauses will probably evolve to use RxCode objects too. 





RxConvert.nrx 


Holds the cost and type of a conversion 








RxConverter.nrx Determines and costs a conversion/coercion, and effects a particular conver- 
sion 
RxError.nrx Handle an Error (see also RxQuit and RxWarn) 





RxException.nrx 


Represents a Java exception 





RxExprParser.nrx 


Parse and generate RxCode for an expression 





RxField.nrx 


Represents a field (property or method) 





RxFixup.nrx 


Changes the sourcefile attribute in a .class file to point to Foo.nrx constant in- 
stead of Foo.java 














RxFlag.nrx Represents option flags 

RxLanguage.nrx Language version and date, and major change list 

RxLevel.nrx Represents a level of semantic nesting. 0=class, 1=method, 2 is method body 
(do groups, etc.) 

RxMessage.nrx Displays/queues an error or warning message. (Offspring of RxError, RxQuit, 


RxPackagelInfo.nrx 


RxWarn) 


Describes a known package 





RxParser.nrx 


NetRexx-specific program/clause parser 





RxProgram.nrx 


Represents a compilation unit (==Program) 





RxQuit.nrx 


Handles severe errors (see also RxError, RxWarn) 





RxSignature.nrx 


Represents a type 








RxStreamer.nrx Handles input and output streams (files), including formatting of output Java 
source 
RxTermParser.nrx Parses terms in expressions 





RxToken.nrx 


Represents a lexical token (see RxClauser) 





RxTracer.nrx 


Generates code for tracing of various types 





RxTranslator.nrx 


top-level’ controller for parsing and compilation. 
44 a) 





RxVariable.nrx 


TABLE 3: Translator source files -2 


Represents a local or class variable, and its cross-reference list 





RxVarpool.nrx 


Collection of known RxVariables 





RxWarn.nrx 


Handles Warnings 








RxChunk.nrx — A chunk of Java sourcecode, destined for the output file (planned to be replaced by 
RxCode objects, long term) 
TABLE 4: Translator source files -3 
RxAssign.nrx handles all assignment clauses 





RxCatch.nrx 





RxClass.nrx 





RxDo.nrx 





RxElse.nrx 





RxEnd.nrx 





RxExit.nrx 





RxFinally.nrx 





RxIf.nrx 





RxImport.nrx 





RxlIterate.nrx 





RxLeave.nrx 





RxLoop.nrx 





RxMethod.nrx 





RxNop.nrx 





RxNumeric.nrx 





RxOptions.nrx 





RxOtherwise.nrx 





RxPackage.nrx 





RxParse.nrx 





RxProperties.nrx 





RxReturn.nrx 





RxSay.nrx 





RxSelect.nrx 





RxSignal.nrx 





RxThen.nrx 





RxTrace.nrx 


RxWhen.nrx 
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30.2. Method resolution 


Until version 3.01 of the NetRExx translator a slightly different way of method resolution 
was used. The chances that this will ever impact your program are very small, but for the 
sake of history preservation (and to clarify the process that is used) the way in which the 
translator looks up and decides to find methods in the inheritance tree are documented 
here. 
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